gwyer/mcp-raganything-researcher

mcp-raganything-researcher

An MCP server that wraps RAG-Anything to provide multimodal RAG over local documents (PDFs, Office, images, tables, equations) and expose it as tools to MCP-aware clients like Claude Desktop.

What it does

• Recursively indexes a folder of documents using RAG-Anything:

  • PDFs, DOC/DOCX, PPT/PPTX, XLS/XLSX
  • Images (PNG/JPG)
  • Text / Markdown

• Builds a multimodal knowledge base (via RAG-Anything + LightRAG) and then lets an LLM:

  • Answer questions across the whole corpus
  • Use hybrid vector + graph retrieval under the hood

• Exposes this via two MCP tools:

  • index_corpus(path: string)
  • ask_corpus(question: string)

Architecture

Claude Desktop (MCP client)
        │
        │  MCP protocol (tools)
        ▼
mcp-raganything-researcher (this repo)
        │
        ├─ RAGAnything.process_document_complete(...)
        └─ RAGAnything.aquery(..., mode="hybrid")

Server Management

Graceful Shutdown

The server includes graceful shutdown handling for SIGINT and SIGTERM signals. When the server receives a shutdown signal, it will:

• Log the shutdown event to stderr
• Clean up resources
• Exit cleanly

Stopping the Server

If you need to manually stop running server processes, use the provided helper script:

cd rag_backend
./stop_server.sh

The script will:

1. Find all running Python processes for server.py
2. Send SIGINT (graceful shutdown signal) to each process
3. Wait 2 seconds for graceful shutdown
4. Report which processes stopped successfully
5. Provide instructions for force-stopping any remaining processes if needed

Manual shutdown:

# Find server processes
pgrep -f "python.*server.py"

# Send graceful shutdown signal
kill -INT <PID>

# Force stop if needed (last resort)
kill -9 <PID>

Troubleshooting

Check Server Logs

When running through Claude Desktop, server logs are available at:

~/Library/Logs/Claude/mcp-server-raganything-researcher.log

View recent logs:

tail -50 ~/Library/Logs/Claude/mcp-server-raganything-researcher.log

Common Issues

1. Server not starting: Check that all paths in claude_desktop_config.json are correct
2. Import errors: Ensure requirements.txt dependencies are installed in the virtual environment
3. Config not found: The server automatically resolves config.toml and .env relative to the script location