RAGFlow Claude MCP Server
RAGFlow Claude MCP-Server
Ein kleiner Model Context Protocol (MCP)-Server, der Claude Desktop (und andere MCP-Clients) mit einer RAGFlow-Instanz verbindet. Er stellt die RAGFlow REST-API als eine Reihe von Tools zur Verfügung, sodass das LLM Wissensdatenbanken abfragen und Dokumenten-Chunks in seinen Kontext ziehen kann.
Dies ist eine Software für den persönlichen Gebrauch, die ich für meine eigene Forschung und Entwicklung geschrieben habe. Sie ist nicht fehlerfrei und der Code ist nicht schön. Er funktioniert für meine Zwecke.
Was er tut
Direkter Abruf: Zieht rohe Dokumenten-Chunks mit Ähnlichkeitswerten vom
/retrieval-Endpunkt von RAGFlow.Multi-KB-Suche: Eine einzelne Abfrage kann mehrere Wissensdatenbanken gleichzeitig durchsuchen.
DSPy-Abfragevertiefung: Optionale iterative Abfrageverfeinerung (nutzt ein LLM, um Zwischenergebnisse zu analysieren und die Abfrage umzuschreiben).
~~Reranking~~ — derzeit auf der RAGFlow-Seite defekt, siehe Bekannte Probleme.
Einstellbare Ergebniskontrolle:
page_size,similarity_threshold,top_k, Paginierung.Dokumentenfilter: Ergebnisse auf ein Dokument innerhalb eines Datensatzes beschränken (Fuzzy-Namensabgleich).
Datensatzsuche nach Name (Groß-/Kleinschreibung ignoriert, Fuzzy) anstelle von ID.
Cloudflare Zero Trust-Authentifizierung, wenn Ihr RAGFlow dahinter liegt.
Related MCP server: RAGBrain MCP
Installation
Klonen:
git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp cd ragflow-claude-desktop-local-mcpInstallieren:
# On macOS, install DSPy first to dodge build issues: pip install git+https://github.com/stanfordnlp/dspy.git uv installKonfigurieren: Kopieren Sie das Beispiel und tragen Sie Ihre RAGFlow-Details ein.
cp config.json.sample config.jsonSchlüssel:
RAGFLOW_BASE_URL: z. B.http://your-ragflow-server:9380RAGFLOW_API_KEY: Ihr RAGFlow API-SchlüsselRAGFLOW_DEFAULT_RERANK: Rerank-Modell (Standardrerank-multilingual-v3.0)CF_ACCESS_CLIENT_ID(optional): Cloudflare Zero Trust Service-Token IDCF_ACCESS_CLIENT_SECRET(optional): Cloudflare Zero Trust Service-Token SecretDSPY_MODEL: DSPy LM (Standardopenai/gpt-4o-mini)OPENAI_API_KEY: erforderlich für DSPy-Vertiefung
Cloudflare Zero Trust
Wenn Ihr RAGFlow hinter Cloudflare Zero Trust liegt, holen Sie sich ein Service-Token aus dem Dashboard und fügen Sie es der config.json hinzu:
{
"CF_ACCESS_CLIENT_ID": "your-client-id.access",
"CF_ACCESS_CLIENT_SECRET": "your-client-secret"
}Wenn beide gesetzt sind, wird jede API-Anfrage mit den Headern CF-Access-Client-Id und CF-Access-Client-Secret gesendet. Es sind keine Codeänderungen erforderlich.
Claude Desktop Konfiguration
{
"mcpServers": {
"ragflow": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/ragflow-claude-desktop-local-mcp",
"ragflow-claude-mcp"
]
}
}
}Tools
ragflow_retrieval_by_name (das Tool, das ich am häufigsten verwende)
Ruft Chunks über einen oder mehrere Datensätze hinweg nach Namen ab. Gibt rohe Chunks mit Ähnlichkeitswerten zurück.
Parameter:
dataset_names(erforderlich) — Liste, z. B.["BASF", "Quant Literature"]query(erforderlich)document_name(optional) — auf ein Dokument beschränken; Fuzzy-Matchtop_k(optional, Standard 1024) — Vektorkandidatensimilarity_threshold(optional, Standard 0.2) — 0.0–1.0page(optional, Standard 1)page_size(optional, Standard 10)use_rerank(optional, Standard false) — derzeit upstream defekt, siehe Bekannte Problemedeepening_level(optional, Standard 0) — DSPy-Verfeinerung, 0–3
ragflow_retrieval
Gleiche Form, nimmt aber dataset_ids: List[str] anstelle von Namen.
Multi-KB-Suche
Sie können in einem Aufruf mehrere Wissensdatenbanken durchsuchen. Stellen Sie sicher, dass sie dasselbe Embedding-Modell verwenden — das Mischen inkompatibler Embeddings verschlechtert die Relevanzwerte.
Use ragflow_retrieval_by_name with dataset_names ["Finance Reports", "Legal Documents"] and query "Summarize the key financial risks and compliance requirements for new market entry."ragflow_list_datasets
Listet jede Wissensdatenbank auf Ihrer RAGFlow-Instanz auf. Keine Parameter. Durchläuft intern alle Seiten.
ragflow_list_documents
Listet Dokumente in einem Datensatz auf. Durchläuft alle Seiten.
dataset_id(erforderlich)
ragflow_get_chunks
Gibt Chunks (mit Referenzen) für ein Dokument zurück.
dataset_id(erforderlich)document_id(erforderlich)
ragflow_list_sessions
Zeigt aktive Chat-Sitzungen pro Datensatz an. Keine Parameter.
ragflow_list_documents_by_name
Listet Dokumente in einem Datensatz auf, gesucht nach Name.
dataset_name(erforderlich)
ragflow_reset_session
Beendet die Chat-Sitzung für einen Datensatz.
dataset_id(erforderlich)
Optimierung des Abrufs
Die Abruf-Tools bieten drei Stellschrauben:
page_size— Chunks pro Seite (Standard 10).similarity_threshold— verwirft Chunks unter diesem Wert (Standard 0.2).top_k— Poolgröße für die Vektorsuche vor dem Filtern (Standard 1024).
Einige Startpunkte, die für mich funktionieren:
Breiterer Abruf:
page_size=15,similarity_threshold=0.15.Enge Präzision:
page_size=5,similarity_threshold=0.4.Intensive Recherche:
page_size=20,similarity_threshold=0.1,deepening_level=1.Schwierige Abfragen:
deepening_level=2.Geschwindigkeit:
deepening_level=0beibehalten und Rerank überspringen.
Beispiele
Grundlegender Abruf nach Name:
Use ragflow_retrieval_by_name with dataset_names ["BASF"] and query "What is BASF's latest income statement? Revenue, operating income, net income, and other key figures."Auf ein Dokument beschränken:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], document_name "annual_report_2023", and query "What were the key financial highlights for 2023?"Dokumentennamen werden per Fuzzy-Match abgeglichen — "annual" findet annual_report_2023.pdf und annual_report_2024.pdf. Wenn mehrere übereinstimmen, wählt der Server das aktuellste aus und listet die Alternativen in den Antwort-Metadaten auf.
DSPy-Vertiefung für eine knifflige Abfrage:
Use ragflow_retrieval_by_name with dataset_names ["Quant Literature"], query "what is a volatility clock", deepening_level 2.Mehrseitig:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], query "BASF business segments", page_size 10, page 2.Verfügbare Ressourcen auflisten:
Use ragflow_list_datasets.Use ragflow_list_documents_by_name with dataset_name "BASF".Spezifische Chunks abrufen:
Use ragflow_get_chunks with dataset_id "43066ee0599411f089787a39c10de57b" and document_id "d74a1c105a3311f09fc94a0fcd8b7722".Größere Prompts
Einige Beispiele, wie ich es von Claude Desktop aus steuere.
Finanzielle Tiefenanalyse:
Help me analyse BASF's recent financials.
1. Use ragflow_retrieval_by_name to search ["BASF"] for the latest income statement
(revenue, operating income, net income). Use page_size 15,
similarity_threshold 0.15, deepening_level 1.
2. Then run ragflow_retrieval_by_name again for the cash flow statement,
page_size 10, similarity_threshold 0.2.
3. Finally look for year-over-year changes with page_size 12,
similarity_threshold 0.18.Mehrsprachige Recherche:
Use ragflow_retrieval_by_name with dataset_names ["BASF"],
query "Was sind die wichtigsten Geschäftsbereiche von BASF?",
deepening_level 2.DSPy erkennt die Abfragesprache und verfeinert sie entsprechend. Ich habe dies für deutsche, englische und gemischtsprachige Abfragen verwendet. Es funktioniert, solange die zugrunde liegenden Dokumente Inhalte in diesen Sprachen haben.
Dokumentgefilterte Recherche:
1. Use ragflow_list_documents_by_name with dataset_name "BASF" to see what's in there.
2. Use ragflow_retrieval_by_name with dataset_names ["BASF"],
document_name "sustainability_report", query "carbon neutrality goals",
page_size 15, deepening_level 1.
3. Follow up with document_name "annual_report_2023" and
query "environmental investments".Cross-KB-Abfrage:
Use ragflow_retrieval_by_name with dataset_names ["BASF", "Industry Reports"],
query "chemical industry sustainability benchmarks",
page_size 12, deepening_level 1.Wie DSPy-Vertiefung funktioniert
deepening_level führt eine LLM-gesteuerte Verfeinerungsschleife über dem Abruf aus:
0: keine Vertiefung (Standard).
1: ein Verfeinerungsdurchgang.
2: zwei Durchgänge mit Lückenanalyse.
3: drei+ Durchgänge plus Ergebniszusammenführung.
Jeder Durchgang: Suche durchführen, die besten Ergebnisse zusammenfassen, das LLM fragen, was fehlt, eine neue Abfrage generieren, diese ausführen. Die Antwort-Metadaten enthalten die ursprüngliche Abfrage, jede verfeinerte Abfrage und die Begründung bei jedem Schritt.
DSPy benötigt:
DSPY_MODEL—openai/gpt-4o-minifunktioniert gutOPENAI_API_KEY
Reranking (derzeit defekt)
Wenn es funktioniert, ersetzt Reranking den Vektor-Cosinus-Score durch den Score des Rerank-Modells (in meiner Erfahrung typischerweise 10–30 % bessere Relevanz). RAGFlow hat derzeit einen bekannten Fehler, bei dem use_rerank=true folgendes erzeugt:
UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol
Lassen Sie also use_rerank=false, bis das Upstream-Problem behoben ist. Der Standard-Vektorabruf funktioniert normal.
Wie die Datensatzsuche funktioniert
Namensabgleich ohne Berücksichtigung der Groß-/Kleinschreibung.
Fuzzy-Match für Teilnamen.
Datensätze werden für die Namenssuche zwischengespeichert; Cache-Misses lösen eine Aktualisierung aus.
Wenn die Suche fehlschlägt, enthält der Fehler die verfügbaren Datensatznamen, damit Sie wissen, was tatsächlich vorhanden war.
Dokumentenabgleich
Wenn Sie document_name übergeben:
Exakte Übereinstimmung gewinnt, dann "beginnt mit", dann "enthält", dann partiell.
Bei Gleichstand gewinnt das zuletzt aktualisierte Dokument.
Namen, die
2024,2023,latest,currentodernewenthalten, erhalten einen kleinen Score-Bonus.Alle Übereinstimmungen werden in den Antwort-Metadaten zurückgegeben, sodass Sie mit einem spezifischeren Namen erneut abfragen können.
Fehlerbehandlung
Angemessene Fehlermeldungen für: API-Fehler, fehlende Datensätze, nicht erreichbares RAGFlow, unterbrochene Sitzungen, ungültige Eingaben und Konfigurationsprobleme. Sensible Werte werden in den Protokollen geschwärzt.
Umgebungsvariablen
RAGFLOW_BASE_URL— überschreibt die Konfigurationsdatei. Standard im Code:http://192.168.122.93:9380(meine lokale Instanz).RAGFLOW_API_KEY— erforderlich.
Entwicklung
Server direkt ausführen:
uv run ragflow-claude-mcpEr lauscht auf stdio, wie MCP-Server das tun.
Entwicklungs-Abhängigkeiten:
uv install --extra devDas installiert pytest + die asyncio/mock/cov-Plugins.
Tests:
uv run pytest
uv run pytest --cov=src --cov-report=html --cov-report=term
uv run pytest tests/test_server.py
uv run pytest -vDie Abdeckung liegt bei etwa 44 % mit 22/23 bestandenen Tests (einer wird aufgrund eines intermittierenden CI-Fehlers übersprungen). Die Tests decken Server-Initialisierung, RAGFlow API-Integration, DSPy-Vertiefung, OpenAI/OpenRouter-Konfigurationszweige und das Laden der Konfiguration ab.
Implementierungshinweise
Die Retrieval-API ist die einzige RAGFlow-Oberfläche, auf die sich der Server tatsächlich verlässt. Keine Abhängigkeiten von Assistent/Chat, keine serverseitige Prompt-Konfiguration — nur Chunks zurück. Einfacher zu durchschauen, einfacher zu debuggen.
Fehlerbehebung
"Dataset not found": Führen Sie
ragflow_list_datasetsaus, um zu sehen, was tatsächlich vorhanden ist.Verbindungsfehler: Überprüfen Sie
RAGFLOW_BASE_URLundRAGFLOW_API_KEY.Server startet nicht: Ist
uv installtatsächlich abgeschlossen?Rohe Chunks benötigt: Das ist
ragflow_retrieval_by_name/ragflow_retrieval.Feststeckende Sitzung:
ragflow_list_sessionsdannragflow_reset_session.Cloudflare 403s: Bestätigen Sie, dass
CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRETmit einem aktiven Service-Token in der Zero Trust-App übereinstimmen.
Bekannte Probleme
Rerank ist upstream defekt
use_rerank=true führt zu Fehlern mit UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol. Dies ist ein Defekt auf RAGFlow-Seite. Workaround: Lassen Sie es ausgeschaltet. Ich beobachte das RAGFlow-Repo auf einen Fix.
Mitwirken
Nur PRs — main ist geschützt. Commits müssen SSH-signiert sein.
Forken.
git checkout -b feature/your-thing.Ändern Sie etwas, schreiben Sie eine klare Commit-Nachricht.
Pushen Sie auf Ihren Fork.
Öffnen Sie einen PR gegen
main.
PRs führen automatisch TruffleHog aus — fügen Sie keine Schlüssel, Token oder Geheimnisse hinzu. Siehe CONTRIBUTING.md für die längere Version.
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