RAGFlow Claude

You run a local MCP server that connects Claude Desktop with RAGFlow to query knowledge bases and manage documents. It enriches the context available to your LLMs, supports direct document retrieval, DSPy-based query refinement, and flexible result control, all from a single, easy-to-run server.

How to use

Start the server locally and connect Claude Desktop to it as an MCP endpoint. You can perform multi-dataset searches, fetch raw document chunks with similarity scores, and refine queries automatically using DSPy. Use the available tools to list datasets, search by dataset name or ID, filter by specific documents, paginate results, and retrieve chunk references for precise analysis.

How to install

Prerequisites you need installed on your system:

• Python (for DSPy and related tooling) and a Python package manager (pip)

• The MCP runtime runner used by Claude Desktop (uv)

Step by step, run the following commands in order.

Clone the project and navigate into it

git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp

cd ragflow-claude-desktop-local-mcp

Install DSPy first to avoid build issues on macOS

pip install git+https://github.com/stanfordnlp/dspy.git

Install all dependencies using UV’s installer

uv install

Run the MCP server directly

uv run ragflow-claude-mcp

Configuration you will use

Create and edit your server configuration to point to your RAGFlow instance and provide necessary credentials. The server expects environment values for the RAGFlow base URL and API key, and may require OpenAI API access for DSPy deepening.

Example environment variable setup (referenced by the server):

RAGFLOW_BASE_URL=http://your-ragflow-server:port
RAGFLOW_API_KEY=YOUR_RAGFLOW_API_KEY
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
DSPY_MODEL=openai/gpt-4o-mini

Claude Desktop configuration

Configure Claude Desktop to connect to this MCP server by adding the following MCP entry:

{
  "mcpServers": {
    "ragflow": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/ragflow-claude-desktop-local-mcp",
        "ragflow-claude-mcp"
      ]
    }
  }
}

Available tools and how to use them

You can query across multiple datasets, fetch raw document chunks, filter by document name, control pagination, and optionally enable reranking and DSPy deepening to refine results.

Result control and filtering

Tune how results are returned with page size, similarity threshold, top_k, and optional reranking. Use DSPy deepening to iteratively refine queries for more accurate results.

Usage examples (Claude Desktop prompts)

Use the ragflow_retrieval_by_name tool with dataset_name to search named knowledge bases and refine results with DSPy when needed.

Troubleshooting

Common issues include ensuring RAGFLOW_BASE_URL and RAGFLOW_API_KEY are correct, and that the MCP server is running with uv. If you encounter session or dataset issues, use the session tools to inspect or reset sessions.

Security and best practices

Keep API keys and tokens secure. Do not expose your OPENAI_API_KEY or RAGFLOW_API_KEY in public channels. Use stable network access to your RAGFlow instance and restrict access to the MCP endpoint as needed.

Available tools

ragflow_retrieval_by_name

Retrieve document chunks by dataset names using the retrieval API, returning raw chunks with similarity scores and optional filtering by document name.

ragflow_retrieval

Retrieve document chunks directly from specified datasets using IDs, returning raw chunks with similarity scores and optional filtering by document name.

ragflow_list_datasets

List all available knowledge bases in your RAGFlow instance.

ragflow_list_documents

List documents within a specific dataset by dataset_id.

ragflow_get_chunks

Get document chunks with references for a specific document.

ragflow_list_sessions

Show active chat sessions for all datasets.

ragflow_list_documents_by_name

List documents in a dataset by its dataset name.

ragflow_reset_session

Reset or clear the chat session for a specific dataset.