This MCP server provides seamless integration between Claude Desktop and RAGFlow by enriching the context available to language models. It exposes tools to retrieve knowledge base content from RAGFlow datasets, supports dataset name lookups, and includes options for reranking, pagination, and DSPy-based query refinement to produce better search results. The server workflows include direct retrieval of raw document chunks with similarity scores, optional reranking, and deepening of queries through DSPy to iteratively improve results. You can use the provided tools to retrieve chunks by dataset name or by dataset IDs, list datasets or documents, and manage sessions across datasets.

To use, configure the MCP in Claude Desktop using the provided mcp configuration example. Then, interact with the available tools such as ragflow_retrieval_by_name for name-based queries, ragflow_retrieval for ID-based retrieval, and helper tools for listing datasets/documents or managing sessions. When issuing a query, you can tune page_size, similarity_threshold, top_k, use_rerank, and deepening_level to balance speed, precision, and quality. For Cloudflare-protected RagFlow instances, provide the optional CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET in your config to ensure authenticated requests.

Prerequisites:

• Python 3.8+ installed
• Access to a RagFlow instance with a compatible API
• Optional: Cloudflare Zero Trust credentials if your RagFlow is protected

Installation steps:

1. Clone the repository git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp cd ragflow-claude-desktop-local-mcp

2. Install DSPy (needed for DSPy-based query refinement)

   On macOS/Linux

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

3. Install project dependencies via the MCP runtime (UV) uv install

4. Prepare configuration

   • Copy sample config and edit your settings: cp config.json.sample config.json

5. Run the MCP server (via Claude Desktop configuration) Use the provided Claude Desktop MCP config example to point to the UVA-based MCP, ensuring the directory path matches your setup:

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

6. Verify operation

   • Ensure RAGFLOW_BASE_URL and RAGFLOW_API_KEY are set in config.json
   • If using Cloudflare Zero Trust, set CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET

7. Optional: Deploy in production using your preferred process manager and ensure network access to RagFlow

Note: The exact directory and MCP name in the uv run command should reflect your local filesystem and the internal MCP entry name (ragflow-claude-mcp in this example).

Tips and common issues:

• If you encounter DSPy-related errors, ensure the DSPy model specified in DSPY_MODEL is accessible with your OpenAI API key (OPENAI_API_KEY).
• For performance tuning, adjust page_size, similarity_threshold, top_k, and deepening_level according to your use case. Lower thresholds and larger page sizes may increase latency.
• When using Cloudflare Zero Trust, ensure the Service Token credentials are valid and that CF_ACCESS_CLIENT_ID/SECRET are correctly set in config.json.
• Document filtering supports fuzzy matching; use dataset_name lookups to simplify queries when you don’t know exact dataset IDs.
• If you upgrade RagFlow or the MCP codebase, re-check the CLI arguments for uv run to ensure compatibility.