RAGFlow Claude MCP Server
This local stdio MCP server lets AI clients search existing RAGFlow knowledge bases and retrieve document chunks with similarity scores.
List available RAGFlow datasets/knowledge bases.
List documents in a dataset by dataset ID or name.
Get chunks with references from a specific document.
Retrieve chunks by dataset IDs or dataset names using a query.
Filter retrieval by document name, pagination, page size, top-k candidates, and similarity threshold.
Optionally enable reranking or DSPy query deepening levels 0–3.
List locally tracked chat sessions and reset a dataset’s tracked session.
It does not install RAGFlow or upload/index documents; it connects to an existing RAGFlow instance.
Supports optional Cloudflare Zero Trust authentication by including CF-Access-Client-Id and CF-Access-Client-Secret headers in API requests when protecting RAGFlow instances behind Cloudflare Zero Trust
Uses OpenAI's GPT-4o-mini model for DSPy query deepening and intelligent query refinement, enabling iterative search improvement and multilingual query handling
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@RAGFlow Claude MCP Server search the BASF dataset for polymer synthesis methods"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
RAGFlow MCP for Claude Desktop, Codex, and Antigravity
Search documents you already have in RAGFlow from your AI client. This local MCP server retrieves document chunks and similarity scores, so you can ask questions across your knowledge bases without copying passages into each conversation.
Start with ordinary retrieval. You need a RAGFlow API key, but no separate OpenAI or OpenRouter key for this server unless you enable optional query deepening. Your AI client still needs its own account or model configuration.
I built this for my own R&D. Try it on a dataset whose contents you know before relying on it for research. The first check is concrete: can your client list that dataset and retrieve a passage you can verify in the original document?
Before you start
You need:
A reachable RAGFlow instance with an API key and at least one parsed, indexed document.
Git, uv, and Python 3.12 or newer. The quickstart uses Python 3.12, which is tested in CI.
Claude Desktop, Codex CLI, Antigravity CLI (
agy), or another client that can launch a local stdio MCP server.
This project connects to an existing RAGFlow installation. It does not install RAGFlow or upload and index your documents.
The MCP process runs on your computer. Queries go to your RAGFlow instance; retrieved content returns to your AI client and may be sent to that client's model provider. Optional DSPy deepening also sends queries and result summaries to the provider you configure below. Check those data paths before using sensitive documents.
Related MCP server: RAGBrain MCP
Install and configure
Run these commands in a terminal, including PowerShell on Windows:
git clone --branch v0.2.1 https://github.com/norandom/ragflow-claude-desktop-local-mcp.git
cd ragflow-claude-desktop-local-mcp
uv sync --locked --python 3.12This checks out the release tag and installs its locked dependencies. A detached-HEAD message is normal for a release checkout.
Create config.json in the cloned directory with these two entries:
{
"RAGFLOW_BASE_URL": "http://your-ragflow-server:9380",
"RAGFLOW_API_KEY": "replace-with-your-ragflow-api-key"
}Use the base URL, without /api/v1. Use HTTPS when connecting across an untrusted network. config.json is ignored by Git, but contains a credential: keep it private. config.json.sample lists optional settings; leave unused placeholder credentials out of your working configuration.
Environment variables override values in the file. RAGFLOW_CONFIG_PATH selects a different config file; otherwise the server reads config.json from its working directory. There is no built-in RAGFlow address or API key.
Connect your client
Choose one client below. Replace /absolute/path/to/ragflow-claude-desktop-local-mcp with the directory you cloned. On Windows, C:/Users/you/Source/ragflow-claude-desktop-local-mcp works in these examples. Quote paths containing spaces.
The client starts the server on demand over stdio. You do not need to start a web server or open a local port.
Claude Desktop
Open Settings, then Developer, then Edit Config. Add the ragflow entry to the existing mcpServers object in claude_desktop_config.json; preserve your other servers.
{
"mcpServers": {
"ragflow": {
"command": "uv",
"args": [
"run",
"--locked",
"--directory",
"/absolute/path/to/ragflow-claude-desktop-local-mcp",
"ragflow-claude-mcp"
]
}
}
}Fully quit and reopen Claude Desktop. If it cannot find uv, replace command with its full executable path. Find it with Get-Command uv in PowerShell or command -v uv on macOS/Linux. See the local MCP setup guide for client configuration and logs.
Codex CLI
Register the local command:
codex mcp add ragflow -- uv run --locked --directory "/absolute/path/to/ragflow-claude-desktop-local-mcp" ragflow-claude-mcp
codex mcp get ragflowStart a new codex session and use /mcp to check the connection. Codex stores MCP settings in ~/.codex/config.toml; alternatively, add this table there instead of running the registration command:
[mcp_servers.ragflow]
command = "uv"
args = ["run", "--locked", "--directory", "/absolute/path/to/ragflow-claude-desktop-local-mcp", "ragflow-claude-mcp"]To use a config file outside the checkout, add --env "RAGFLOW_CONFIG_PATH=/absolute/path/to/config.json" before the -- in the registration command. See OpenAI's MCP documentation for client settings.
Antigravity CLI (agy)
Register the same stdio command:
agy mcp add --type stdio ragflow uv run --locked --directory "/absolute/path/to/ragflow-claude-desktop-local-mcp" ragflow-claude-mcp
agy mcp listStart a new agy session and open /mcp to check the server. If it is disabled, run agy mcp enable ragflow.
For a config file outside the checkout, put --env "RAGFLOW_CONFIG_PATH=/absolute/path/to/config.json" before ragflow in the registration command. The agy mcp add options belong before the server name; the arguments after uv belong to uv. See Antigravity's MCP documentation for details.
Other MCP clients
Use uv as the command and the same argument list shown for Claude Desktop. This server exposes stdio, not an HTTP MCP endpoint: do not enter your RAGFlow URL as an MCP server URL.
Verify your first retrieval
In your client, ask:
Use ragflow_list_datasets and show the available dataset names.Then substitute an actual dataset name and a question whose answer you know:
Use ragflow_retrieval_by_name with dataset_names ["My Knowledge Base"],
query "What does the document say about our backup schedule?",
page_size 5, deepening_level 0, and use_rerank false.
Show the returned passages and their document references before summarizing.A working connection returns dataset names, then relevant chunks from the selected dataset. Compare a returned passage with its source. If the passage is missing or irrelevant, check indexing and retrieval settings before enabling deepening. A fluent answer alone does not establish that retrieval worked.
For a team trial, have someone familiar with the dataset check a few known-answer queries. Share the queries and source checks with a colleague who uses the same material before adding more datasets.
Search options and tools
ragflow_retrieval_by_name is the usual starting point. It takes dataset_names (a list) and query. Use ragflow_retrieval with dataset_ids when you want to avoid ambiguity in name matching.
Option | Default | When to change it |
| No filter | Restrict retrieval to a document; names match fuzzily. |
|
| Request fewer chunks for a quick check or more for broader research. |
|
| Fetch another page. |
|
| Lower it to admit more results; raise it to filter weak matches. |
|
| Change the candidate pool used for vector search. |
|
| Enable after checking your RAGFlow reranker configuration. |
|
| Try up to 1, 2, or 3 refinement passes after configuring DSPy. |
To search several datasets, pass multiple names, for example ["Finance Reports", "Legal Documents"]. Use datasets with compatible embedding models. Dataset lookup is case-insensitive and supports partial names; use exact names or IDs when several are similar.
For a document-specific query, first list documents, then use a specific document_name. Fuzzy matching can select a different document than you intended; inspect the response metadata for matches.
Tool | Required inputs | Purpose |
| None | List datasets accessible with your API key. |
|
| List documents in a dataset. |
|
| List documents using a dataset name. |
|
| Read chunks for a document. |
|
| Retrieve chunks by dataset IDs. |
|
| Retrieve chunks by dataset names. |
| None | Inspect locally tracked chat sessions. |
|
| Reset a tracked session. |
Optional configuration
Query deepening with DSPy
Deepening asks an additional LLM to analyze retrieved results and rewrite the query. It adds latency and provider usage charges. Leave deepening_level=0 for ordinary retrieval.
For OpenAI, add these entries to your config.json:
{
"PROVIDER": "openai",
"DSPY_MODEL": "openai/gpt-4o-mini",
"OPENAI_API_KEY": "replace-with-your-openai-api-key"
}For OpenRouter, use:
{
"PROVIDER": "openrouter",
"DSPY_MODEL": "openai/gpt-4o-mini",
"OPENROUTER_API_KEY": "replace-with-your-openrouter-api-key"
}These are additions to the RAGFlow settings, not replacement files. Restart the MCP server after changing configuration. OPENROUTER_SITE_URL and OPENROUTER_SITE_NAME are optional attribution settings.
Start with deepening_level=1 and compare its results with the original query. Levels 1 through 3 set the maximum refinement passes; the loop can stop early. The implementation returns the last result set, not a merged union of all searches. Metadata records the refinement process. Configuration or refinement failures can fall back to ordinary retrieval, so check metadata and logs if deepening appears to have no effect.
Cloudflare Zero Trust
If RAGFlow is behind Cloudflare Access, add both CF_ACCESS_CLIENT_ID and CF_ACCESS_CLIENT_SECRET from an authorized service token. The server sends the corresponding Access headers with API requests. Leave both unset for a direct RAGFlow connection.
Reranking
RAGFLOW_DEFAULT_RERANK selects the reranking model when use_rerank=true. This project has encountered UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol with reranking on RAGFlow. That observation does not establish the status of every RAGFlow version. Leave reranking off for the first retrieval; if you see this error, use use_rerank=false and check the provider URL configured in RAGFlow.
Troubleshooting
Symptom | Check next |
Client cannot start the server | Run |
Server waits silently in a terminal | It speaks MCP over stdio. Let your client launch it; this is not an interactive shell or HTTP server. |
Missing configuration | Confirm |
Connection error or 401 | Check the RAGFlow base URL, network access, and API key. The base URL must include |
Cloudflare 403 | Check both Access service-token values and the application's Access policy. |
Dataset not found | Call |
Empty or irrelevant results | Check that documents are indexed. Try a known phrase and a lower |
Deepening has no effect | Check the provider key and response metadata. Ordinary retrieval can still succeed when deepening fails. |
For a startup check outside your client:
uv run --locked --directory "/absolute/path/to/ragflow-claude-desktop-local-mcp" ragflow-claude-mcpErrors go to stderr. A running process waiting for MCP input is expected; stop it with Ctrl+C. Review logs before sharing them: queries, document excerpts, and configuration details can be sensitive.
Limits and security
DSPy depends on DiskCache 5.6.3, which has an unresolved pickle-deserialization advisory, GHSA-w8v5-vhqr-4h9v. DSPy enables disk caching by default. Keep its cache directory private to the account running this server; do not share or import caches from untrusted sources. No patched DiskCache release was listed during the v0.2.1 audit.
The v0.2.1 local test run passed 28 tests with 49% coverage. Those checks use mocks; they do not certify your RAGFlow version, document relevance, or model-provider setup. See CHANGELOG.md for the maintenance changes and audit findings.
Update or remove
To update a release checkout, fetch tags, check out the desired tag, run uv sync --locked --python 3.12, then restart your client. Keep your private config.json. To roll back, check out the previous tag and sync again; dependency security fixes may be lost on rollback.
To disconnect, remove the ragflow entry from Claude Desktop, run codex mcp remove ragflow, or run agy mcp remove ragflow. Restart the client. Removing the client entry does not delete your RAGFlow data.
Development
git switch main
git pull --ff-only origin main
uv sync --locked --extra dev
uv run --locked pytest
uv run --locked pytest --cov=src/ragflow_claude_mcp --cov-report=term-missing
uv buildThe release workflow runs the tests and builds packages with uv on Python 3.12. The .dagger module is available for separate container-based checks. Maintainers work directly on main and keep no long-lived feature branches. Use SSH-signed commits as described in CONTRIBUTING.md and COMMIT_SIGNING.md.
Available Tools
8 toolsragflow_get_chunksC
Get chunks with references from a specific document
Inputs: dataset_id (required), document_id (required).
ragflow_list_datasetsA
List all available datasets/knowledge bases in RAGFlow
Inputs: no named parameters.
ragflow_list_documentsC
List documents in a specific dataset
Inputs: dataset_id (required).
ragflow_list_documents_by_nameC
List documents in a dataset by dataset name
Inputs: dataset_name (required).
ragflow_list_sessionsB
List active chat sessions for all datasets
Inputs: no named parameters.
ragflow_reset_sessionB
Reset/clear the chat session for a specific dataset
Inputs: dataset_id (required).
ragflow_retrievalB
Retrieve document chunks directly from RAGFlow datasets using the retrieval API. Returns raw chunks with similarity scores.
Inputs: query (required), dataset_ids (required), page, top_k, +5 more.
ragflow_retrieval_by_nameB
Retrieve document chunks by dataset names using the retrieval API. Returns raw chunks with similarity scores.
Inputs: query (required), dataset_names (required), page, top_k, +5 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have distinct purposes, but ragflow_list_documents and ragflow_retrieval each have an alternative by-name variant, which could cause confusion if descriptions are not heeded. However, descriptions clarify the difference between ID-based and name-based operations, keeping overlap minimal.
All tools follow a consistent verb_noun pattern with snake_case and the 'ragflow_' prefix. Variations like '_by_name' are systematic and predictable, enhancing readability for agents.
With 8 tools, the set is well-scoped for a knowledge base retrieval server. Each tool serves a clear function, and the count is neither too sparse nor overwhelming for the intended purpose.
The tool surface covers listing datasets, listing documents, retrieving chunks, and managing chat sessions. It lacks create/update/delete operations, but given the likely read-heavy focus of the server, these gaps are acceptable and do not impede the primary retrieval workflow.
Maintenance
Related MCP Connectors
Connect your team's living knowledge base — docs, data, issues, CRM — to Claude and ChatGPT.
Cloud or self-hosted knowledge for AI agents: hybrid search, reranking, GraphRAG, scoped MCP tools.
Ingest, manage, and retrieve documents for RAG-powered AI applications
Ask your own documents and get answers that cite the source passage. Workspace knowledge bases over MCP for Cursor, Claude and any MCP client.
Related MCP Servers
- FlicenseAqualityDmaintenanceIntegrates R2R (Retrieval-Augmented Generation) with Claude Desktop, enabling semantic search across knowledge bases and RAG-based question answering with support for vector, graph, web, and document search.2-
- AlicenseAqualityFmaintenanceConnects Claude Desktop to a RAGBrain knowledge base to enable semantic search, document retrieval, and namespace management. It allows users to browse collections, discover documents by topic, and access full text content through natural language.5MIT
- AlicenseAqualityDmaintenanceProvides semantic search capabilities by connecting Claude Desktop to a Cloudflare Workers backend powered by Vectorize. It enables natural language querying of knowledge bases using vector similarity and edge-based embedding generation.2MIT
- AlicenseNot gradedqualityDmaintenanceEnables semantic retrieval and knowledge base management through the RAGFlow API, including dataset, document, chunk, chat, and graph operations.7MIT