Skip to main content
Glama
RAGFlow Claude MCP Server

RAGFlow Claude MCP Server

by norandom

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

  1. Klonen:

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

    # On macOS, install DSPy first to dodge build issues:
    pip install git+https://github.com/stanfordnlp/dspy.git
    
    uv install
  3. Konfigurieren: Kopieren Sie das Beispiel und tragen Sie Ihre RAGFlow-Details ein.

    cp config.json.sample config.json

    Schlüssel:

    • RAGFLOW_BASE_URL: z. B. http://your-ragflow-server:9380

    • RAGFLOW_API_KEY: Ihr RAGFlow API-Schlüssel

    • RAGFLOW_DEFAULT_RERANK: Rerank-Modell (Standard rerank-multilingual-v3.0)

    • CF_ACCESS_CLIENT_ID (optional): Cloudflare Zero Trust Service-Token ID

    • CF_ACCESS_CLIENT_SECRET (optional): Cloudflare Zero Trust Service-Token Secret

    • DSPY_MODEL: DSPy LM (Standard openai/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-Match

  • top_k (optional, Standard 1024) — Vektorkandidaten

  • similarity_threshold (optional, Standard 0.2) — 0.0–1.0

  • page (optional, Standard 1)

  • page_size (optional, Standard 10)

  • use_rerank (optional, Standard false) — derzeit upstream defekt, siehe Bekannte Probleme

  • deepening_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=0 beibehalten 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-mini funktioniert gut

  • OPENAI_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, current oder new enthalten, 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-mcp

Er lauscht auf stdio, wie MCP-Server das tun.

Entwicklungs-Abhängigkeiten:

uv install --extra dev

Das 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 -v

Die 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_datasets aus, um zu sehen, was tatsächlich vorhanden ist.

  • Verbindungsfehler: Überprüfen Sie RAGFLOW_BASE_URL und RAGFLOW_API_KEY.

  • Server startet nicht: Ist uv install tatsächlich abgeschlossen?

  • Rohe Chunks benötigt: Das ist ragflow_retrieval_by_name / ragflow_retrieval.

  • Feststeckende Sitzung: ragflow_list_sessions dann ragflow_reset_session.

  • Cloudflare 403s: Bestätigen Sie, dass CF_ACCESS_CLIENT_ID / CF_ACCESS_CLIENT_SECRET mit 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.

  1. Forken.

  2. git checkout -b feature/your-thing.

  3. Ändern Sie etwas, schreiben Sie eine klare Commit-Nachricht.

  4. Pushen Sie auf Ihren Fork.

  5. Ö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 tools
ragflow_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

    B3.4/5.0

    Scored across 8 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      D
      maintenance
      Integrates 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
      -
    • A
      license
      A
      quality
      F
      maintenance
      Connects 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.
      5
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Provides 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.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables semantic retrieval and knowledge base management through the RAGFlow API, including dataset, document, chunk, chat, and graph operations.
      7
      MIT