evgenygurin/r2r-mcp-server

R2R MCP Server

Model Context Protocol server for R2R - Expose R2R's powerful RAG capabilities to AI assistants through a standardized MCP interface.

Current Status

Quick Setup Options:

1. FastMCP Cloud (Recommended) - Connect to hosted server with API key:

   # See "Alternative: Connect to FastMCP Cloud" section below
   # No local setup required!
   

2. Local Setup - Run server locally:

   ./setup-cursor.sh  # Run this first, then configure Cursor
   

Overview

This MCP server provides AI assistants (like Claude) with access to R2R's production-ready RAG system, including:

• Document Management: Upload, list, delete, update documents
• Hybrid Search: Semantic, keyword, and combined search strategies
• RAG & Agents: Question answering with citations and conversational agents
• Collections: Organize documents into logical groups
• Knowledge Graphs: Extract and query entity-relationship graphs

Quick Start

1. Installation

cd mcp_server

# Install dependencies
pip install -r requirements.txt

# OR use uv (recommended)
uv pip install -r requirements.txt

2. Configuration

Create a .env file (or set environment variables):

# R2R Connection
R2R_BASE_URL=https://api.136-119-36-216.nip.io  # or http://localhost:7272
R2R_EMAIL=your@email.com
R2R_PASSWORD=your_password

# Optional: MCP Server Settings
MCP_SERVER_NAME=R2R MCP Server
MCP_LOG_LEVEL=INFO
MCP_CACHE_TTL=300

See .env.example for all configuration options.

3. Run the Server

# Run directly
python server.py

# Or make it executable
chmod +x server.py
./server.py

The server runs using stdio transport (standard for MCP).

4. Configure in Claude Desktop (Local Server)

For local server, add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "r2r-local": {
      "command": "python3",
      "args": ["/absolute/path/to/r2r_mcp_server/server.py"],
      "env": {
        "R2R_BASE_URL": "http://34.134.54.139:7272",
        "R2R_EMAIL": "your@email.com",
        "R2R_PASSWORD": "your_password"
      }
    }
  }
}

For FastMCP Cloud (recommended), see "Alternative: Connect to FastMCP Cloud" section below.

Restart Claude Desktop. The R2R tools should now be available!

Alternative: Connect to FastMCP Cloud ☁️

Instead of running the server locally, you can connect to the hosted R2R MCP Server on FastMCP Cloud at https://r2r-mcp-server.fastmcp.app/mcp.

Benefits:

• ✅ No local setup required
• ✅ Always available (24/7)
• ✅ Automatic updates
• ✅ API key authentication

Getting Your API Key

1. Visit FastMCP Cloud
2. Sign in with your GitHub account
3. Navigate to your deployed r2r-mcp-server project
4. Go to Settings → API Keys
5. Generate a new API key
6. Copy and use it in your client configuration

Security Note: Keep your API key secure and never commit it to version control.

For Claude Desktop (Cloud Connection)

Claude Desktop requires a local proxy to connect to FastMCP Cloud. The proxy file r2r_cloud_proxy.py is included in this repository and connects to https://r2r-mcp-server.fastmcp.app/mcp.

Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "r2r-cloud": {
      "command": "python3",
      "args": ["/Users/laptop/dev/r2r_mcp_server/r2r_cloud_proxy.py"],
      "env": {
        "MCP_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Note:

• Replace the path in args with the absolute path to r2r_cloud_proxy.py on your system
• Replace YOUR_API_KEY_HERE with your actual API key from FastMCP Cloud
• Restart Claude Desktop completely after saving the configuration

For Cursor IDE

Add to ~/.cursor/mcp.json or your workspace MCP configuration:

{
  "mcpServers": {
    "r2r-cloud": {
      "url": "https://r2r-mcp-server.fastmcp.app/mcp",
      "transport": "streamable-http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Note: Replace YOUR_API_KEY_HERE with your actual API key from FastMCP Cloud.

For Cline (VS Code Extension)

Add to VS Code settings or Cline configuration:

{
  "mcpServers": {
    "r2r-cloud": {
      "url": "https://r2r-mcp-server.fastmcp.app/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY_HERE"
      }
    }
  }
}

Alternative: Using FastMCP CLI (Easier for Claude Desktop)

If you have fastmcp installed, you can automatically configure Claude Desktop:

# Install fastmcp if needed
pip install fastmcp

# Create .env file with your API key
echo "MCP_API_KEY=your-api-key-here" > .env

# Install the proxy server
fastmcp install claude-desktop r2r_cloud_proxy.py --name "r2r-cloud" --env-file .env

This will automatically configure Claude Desktop with the correct paths and environment variables.

Restart Your Client

After adding the configuration:

1. Claude Desktop: Restart the application
2. Cursor: Reload the window or restart Cursor
3. Cline: Reload VS Code window

The R2R MCP Server tools should now be available in your AI assistant!

Benefits of FastMCP Cloud

• ✅ No local setup required - Connect immediately from any device
• ✅ Always available - 24/7 uptime with automatic scaling
• ✅ Automatic updates - Server updates on every push to main
• ✅ SSL/TLS encryption - Secure HTTPS connections
• ✅ API key authentication - Built-in access control
• ✅ Free tier during beta - No cost for development and testing

Agent Rules & Development Guidelines

This repository includes comprehensive agent rules that are automatically detected by AI coding assistants like Codegen, Claude Code, Cursor, and others.

📋 Available Rule Files

🎯 What These Rules Cover

• FastMCP Development Standards - Pre-commit workflow, code quality standards
• Critical Architecture Patterns - Singleton client, configuration system, error handling
• Tool Development Workflow - Step-by-step guide for adding new MCP tools
• R2R SDK v3+ API Patterns - Correct usage of R2R SDK
• Testing Best Practices - Async testing, in-memory transport patterns
• Known Issues & Workarounds - Common problems and solutions

🤖 For AI Assistants

The agent rules provide context about:

• Mandatory code patterns (never violate)
• Pre-commit validation workflow
• Tool return format conventions
• Error handling standards
• Testing requirements

👥 For Human Developers

See:

• AGENTS.md - Quick reference and core principles
• CLAUDE.md - Comprehensive development guide with examples
• .env.example - Environment configuration options

🔄 Rule Hierarchy (when using Codegen)

When multiple rules exist, preference order is:

1. User Rules - Your personal coding preferences
2. Repository Rules - This project's standards (AGENTS.md, .cursorrules, CLAUDE.md)
3. Organization Rules - Team-wide standards

All rule files are automatically discovered and included in agent context when working on this repository.

Available Tools

🗂️ Document Management

🔍 Search

🤖 RAG & Agents

📚 Collections

🕸️ Knowledge Graphs

ℹ️ System

Common Workflows

Basic RAG Workflow

1. Check connection:
   get_system_status()

2. Upload document:
   upload_document(file_path="/path/to/document.pdf")

3. Search for information:
   search(query="authentication methods")

4. Ask questions:
   rag_query(query="How do I implement OAuth2 authentication?")

Organizing with Collections

1. Create collection:
   create_collection(name="api-docs", description="API documentation")

2. Upload to collection:
   upload_document(
       file_path="/path/to/doc.pdf",
       collection_ids=["collection_id"]
   )

3. Search within collection:
   search(query="...", collection_ids=["collection_id"])

Building Knowledge Graphs

1. Upload documents:
   upload_document(file_path="/path/to/doc.pdf")

2. Extract graph:
   extract_knowledge_graph(
       document_id="doc_id",
       entity_types=["Person", "Technology", "Organization"]
   )

3. Query graph:
   graph_search(query="technologies used for authentication")

Conversational RAG

1. Start conversation:
   result1 = agent_query(query="What is OAuth2?")
   conv_id = result1["conversation_id"]

2. Follow up (maintains context):
   agent_query(
       query="How does it differ from API keys?",
       conversation_id=conv_id
   )

3. Continue conversation:
   agent_query(
       query="Show me implementation examples",
       conversation_id=conv_id
   )

Tool Usage Tips

Search Best Practices

• Hybrid search (default): Best for general queries
• Vector search: For conceptual/semantic queries
• Keyword search: For exact matches (IDs, names, specific terms)
• Start with limit=5-10, increase if needed
• Use collection_ids to narrow search scope

RAG Best Practices

• Use search_limit=3-5 for focused answers
• Use search_limit=10-20 for comprehensive answers
• Set temperature=0.0 for factual, deterministic responses
• Set temperature=0.7-1.0 for creative explanations
• Check sources in response for citation verification

Collection Organization

• Create collections BEFORE uploading documents
• Use descriptive names: api-docs, legal-contracts, research-papers
• Add rich metadata during upload for better filtering
• Documents can belong to multiple collections

Knowledge Graph Tips

• Extract graphs from clean, well-structured documents first
• Specify entity_types and relation_types for focused extraction
• Update/merge entities to improve graph quality over time
• Combine graph search with document search for best results

Response Format

All tools return a dictionary with:

{
    "status": "success" | "error",
    "formatted": "Human-readable output",
    "next_steps": ["Suggested next actions"],
    # Tool-specific fields...
}

Success Response Example

{
    "status": "success",
    "document_id": "abc123",
    "message": "Document uploaded successfully...",
    "formatted": "Human-readable message with next steps",
    "next_steps": [
        "search(query='...')",
        "rag_query(query='...')",
    ]
}

Error Response Example

{
    "status": "error",
    "error": "Error description with context",
    "suggestion": "How to fix the issue"
}

Architecture

mcp_server/
├── server.py              # Main MCP server (FastMCP)
├── config.py              # Configuration management
├── requirements.txt       # Python dependencies
├── tools/                 # MCP tool implementations
│   ├── documents.py       # Document management
│   ├── search.py          # Search operations
│   ├── rag.py            # RAG and agent queries
│   ├── collections.py     # Collection management
│   └── graphs.py         # Knowledge graph operations
├── utils/                # Utilities
│   ├── client.py         # R2R client singleton
│   └── formatting.py     # Response formatting
└── tests/                # Tests (future)

Configuration Reference

Environment Variables

Troubleshooting

Connection Issues

# Check R2R server is running
curl $R2R_BASE_URL/v3/health

# Test authentication
# (see R2R docs for auth endpoints)

# Check MCP server configuration
python server.py
# Should show "Connected to R2R at ..." in logs

Tool Call Failures

• Authentication errors: Check R2R_EMAIL and R2R_PASSWORD
• Not found errors: Use list_documents() or list_collections() first
• Timeout errors: Reduce limit parameter or simplify query
• Network errors: Verify R2R_BASE_URL and network connectivity

Debugging

# Enable debug logging
export MCP_LOG_LEVEL=DEBUG
python server.py

# Check tool registration
python -c "from server import mcp; print([t.name for t in mcp.list_tools()])"

# Test R2R client directly
python -c "from utils.client import get_r2r_client; client = get_r2r_client(); print(client.system.health())"

Development

Adding New Tools

1. Create tool function in appropriate tools/*.py file:

async def my_new_tool(param: str) -> dict:
    """
    Clear, AI-friendly description of what this tool does.

    Args:
        param: Parameter description

    Returns:
        dict: Response format
    """
    from utils.client import get_r2r_client
    from utils.formatting import format_error_message

    try:
        client = get_r2r_client()
        # Implementation...
        return {"status": "success", ...}
    except Exception as e:
        return {
            "status": "error",
            "error": format_error_message(e, "context")
        }

2. Import and register in server.py:

from tools.module import my_new_tool

mcp.tool(my_new_tool)

3. Test the tool:

python server.py
# Check that tool appears in registered tools list

Testing

# Run tests (future)
pytest tests/

# Manual testing
python
>>> from tools.search import search
>>> import asyncio
>>> result = asyncio.run(search(query="test"))
>>> print(result)

Examples

See examples/ directory (future) for:

• Complete workflow examples
• Integration with Claude Desktop
• Advanced use cases
• Custom tool development

Contributing

Contributions welcome! Please:

1. Follow existing code style and patterns
2. Add comprehensive docstrings (AI-friendly descriptions)
3. Include error handling and formatting
4. Update documentation

License

This MCP server is part of the R2R project. See R2R license for details.

Resources

• R2R Documentation: https://r2r-docs.sciphi.ai
• FastMCP Documentation: https://github.com/jlowin/fastmcp
• MCP Protocol: https://modelcontextprotocol.io
• R2R GitHub: https://github.com/SciPhi-AI/R2R
• R2R Discord: https://discord.gg/p6KqD2kjtB

Support

• Issues: https://github.com/SciPhi-AI/R2R/issues
• Discord: https://discord.gg/p6KqD2kjtB
• Documentation: https://r2r-docs.sciphi.ai

Built with:

• R2R - Production RAG system
• FastMCP - Python MCP framework
• Claude - AI assistant integration