RAGFlow Claude MCP Server
RAGFlow Claude MCP サーバー
RAGFlow インスタンスを Claude Desktop (およびその他の MCP クライアント) に接続するための小さな Model Context Protocol (MCP) サーバーです。RAGFlow REST API をいくつかのツールとして公開し、LLM がナレッジベースをクエリしてドキュメントのチャンクをコンテキストに取り込めるようにします。
これは私自身の研究開発のために書いた個人用ソフトウェアです。バグがないわけではなく、コードも綺麗ではありません。私が必要とする用途には機能しています。
機能
直接取得: RAGFlow の
/retrievalエンドポイントから類似度スコア付きの生のドキュメントチャンクを取得します。マルチ KB 検索: 1 つのクエリで複数のナレッジベースを同時に検索できます。
DSPy クエリ深化: オプションの反復的なクエリ洗練(LLM を使用して中間結果を分析し、クエリを書き換えます)。
~~再ランキング~~ — 現在 RAGFlow 側で壊れています。既知の問題 を参照してください。
調整可能な結果制御:
page_size、similarity_threshold、top_k、ページネーション。ドキュメントフィルタ: データセット内の 1 つのドキュメントに結果を制限します(あいまいな名前マッチング)。
ID ではなく名前によるデータセット検索(大文字小文字を区別しない、あいまい検索)。
RAGFlow が Cloudflare Zero Trust の背後にある場合の認証。
Related MCP server: RAGBrain MCP
インストール
クローン:
git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp cd ragflow-claude-desktop-local-mcpインストール:
# On macOS, install DSPy first to dodge build issues: pip install git+https://github.com/stanfordnlp/dspy.git uv install設定: サンプルをコピーし、RAGFlow の詳細を入力します。
cp config.json.sample config.jsonキー:
RAGFLOW_BASE_URL: 例:http://your-ragflow-server:9380RAGFLOW_API_KEY: RAGFlow API キーRAGFLOW_DEFAULT_RERANK: 再ランキングモデル(デフォルトrerank-multilingual-v3.0)CF_ACCESS_CLIENT_ID(オプション): Cloudflare Zero Trust サービス・トークン IDCF_ACCESS_CLIENT_SECRET(オプション): Cloudflare Zero Trust サービス・トークン・シークレットDSPY_MODEL: DSPy LM(デフォルトopenai/gpt-4o-mini)OPENAI_API_KEY: DSPy の深化に必要
Cloudflare Zero Trust
RAGFlow が Cloudflare Zero Trust の背後にある場合は、ダッシュボードからサービス・トークンを取得し、config.json に追加します:
{
"CF_ACCESS_CLIENT_ID": "your-client-id.access",
"CF_ACCESS_CLIENT_SECRET": "your-client-secret"
}両方が設定されると、すべての API リクエストが CF-Access-Client-Id および CF-Access-Client-Secret ヘッダーと共に送信されます。コードの変更は不要です。
Claude Desktop 設定
{
"mcpServers": {
"ragflow": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/ragflow-claude-desktop-local-mcp",
"ragflow-claude-mcp"
]
}
}
}ツール
ragflow_retrieval_by_name (私が最もよく使うもの)
名前で 1 つ以上のデータセットにわたってチャンクを取得します。類似度スコア付きの生のチャンクを返します。
パラメータ:
dataset_names(必須) — リスト、例:["BASF", "Quant Literature"]query(必須)document_name(オプション) — 1 つのドキュメントに制限。あいまい一致top_k(オプション、デフォルト 1024) — ベクトル候補similarity_threshold(オプション、デフォルト 0.2) — 0.0–1.0page(オプション、デフォルト 1)page_size(オプション、デフォルト 10)use_rerank(オプション、デフォルト false) — 現在アップストリームで壊れています。既知の問題を参照deepening_level(オプション、デフォルト 0) — DSPy 洗練、0–3
ragflow_retrieval
形状は同じですが、名前の代わりに dataset_ids: List[str] を受け取ります。
マルチ KB 検索
1 回の呼び出しで複数のナレッジベースを検索できます。それらが同じ埋め込みモデルを共有していることを確認してください。互換性のない埋め込みを混在させると、関連性スコアが低下します。
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
RAGFlow インスタンス上のすべてのナレッジベースをリストします。パラメータなし。内部的にすべてのページを走査します。
ragflow_list_documents
データセット内のドキュメントをリストします。すべてのページを走査します。
dataset_id(必須)
ragflow_get_chunks
1 つのドキュメントのチャンク(参照付き)を返します。
dataset_id(必須)document_id(必須)
ragflow_list_sessions
データセットごとのアクティブなチャットセッションを表示します。パラメータなし。
ragflow_list_documents_by_name
名前で検索されたデータセット内のドキュメントをリストします。
dataset_name(必須)
ragflow_reset_session
データセットのチャットセッションを破棄します。
dataset_id(必須)
取得の調整
取得ツールには 3 つのノブがあります:
page_size— ページあたりのチャンク数(デフォルト 10)。similarity_threshold— このスコアを下回るチャンクを除外(デフォルト 0.2)。top_k— フィルタリング前のベクトル検索のプールサイズ(デフォルト 1024)。
私が使用している開始点:
より広いリコール:
page_size=15,similarity_threshold=0.15。厳密な精度:
page_size=5,similarity_threshold=0.4。詳細な調査:
page_size=20,similarity_threshold=0.1,deepening_level=1。難しいクエリ:
deepening_level=2。速度:
deepening_level=0に保ち、再ランキングをスキップ。
例
名前による基本的な取得:
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."1 つのドキュメントに制限:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], document_name "annual_report_2023", and query "What were the key financial highlights for 2023?"ドキュメント名はあいまい一致します — "annual" は annual_report_2023.pdf と annual_report_2024.pdf にヒットします。複数一致する場合、サーバーは最新のものを選択し、応答メタデータに代替案をリストします。
難しいクエリに対する DSPy の深化:
Use ragflow_retrieval_by_name with dataset_names ["Quant Literature"], query "what is a volatility clock", deepening_level 2.複数ページ:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], query "BASF business segments", page_size 10, page 2.利用可能なものをリスト:
Use ragflow_list_datasets.Use ragflow_list_documents_by_name with dataset_name "BASF".特定のチャンクを取得:
Use ragflow_get_chunks with dataset_id "43066ee0599411f089787a39c10de57b" and document_id "d74a1c105a3311f09fc94a0fcd8b7722".より大きなプロンプト
Claude Desktop からこれをどのように操作するかの例。
財務の詳細調査:
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.多言語調査:
Use ragflow_retrieval_by_name with dataset_names ["BASF"],
query "Was sind die wichtigsten Geschäftsbereiche von BASF?",
deepening_level 2.DSPy はクエリ言語を検出し、それに応じて洗練します。ドイツ語、英語、混合言語のクエリで使用しました。基盤となるドキュメントにそれらの言語のコンテンツが含まれている限り機能します。
ドキュメントフィルタリングされた調査:
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".KB 横断クエリ:
Use ragflow_retrieval_by_name with dataset_names ["BASF", "Industry Reports"],
query "chemical industry sustainability benchmarks",
page_size 12, deepening_level 1.DSPy の深化の仕組み
deepening_level は、取得の上に LLM 主導の洗練ループを実行します:
0: 深化なし(デフォルト)。
1: 1 回の洗練パス。
2: ギャップ分析を伴う 2 回のパス。
3: 3 回以上のパスと結果の統合。
各パス: 検索を実行し、上位結果を要約し、LLM に何が欠けているかを尋ね、新しいクエリを生成し、それを実行します。応答メタデータには、元のクエリ、すべての洗練されたクエリ、および各ステップでの推論が含まれます。
DSPy に必要なもの:
DSPY_MODEL—openai/gpt-4o-miniが正常に動作しますOPENAI_API_KEY
再ランキング(現在壊れています)
動作している場合、再ランキングはベクトルコサインスコアを再ランキングモデルのスコアに置き換えます(私の経験では、関連性が通常 10~30% 向上します)。RAGFlow には現在、use_rerank=true が以下を生成するという既知のバグがあります:
UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol
そのため、アップストリームの問題が修正されるまで use_rerank=false のままにしてください。標準のベクトル取得は通常通り機能します。
データセット検索の仕組み
大文字小文字を区別しない名前マッチング。
部分名に対するあいまい一致。
データセットは名前検索のためにキャッシュされます。キャッシュミスは更新をトリガーします。
検索が失敗した場合、エラーには利用可能なデータセット名が含まれるため、実際に何が存在したかを知ることができます。
ドキュメントマッチング
document_name を渡す場合:
完全一致が優先され、次に「で始まる」、次に「含む」、次に部分一致となります。
同点の場合、最近更新されたドキュメントが優先されます。
2024、2023、latest、current、またはnewを含む名前には小さなスコアボーナスが与えられます。すべての一致は応答メタデータで返されるため、より具体的な名前で再発行できます。
エラー処理
API エラー、データセットの欠落、到達不能な RAGFlow、壊れたセッション、無効な入力、設定の問題に対する妥当なエラーメッセージ。機密値はログで編集されます。
環境変数
RAGFLOW_BASE_URL— 設定ファイルを上書きします。コード内のデフォルト:http://192.168.122.93:9380(私のローカルインスタンス)。RAGFLOW_API_KEY— 必須。
開発
サーバーを直接実行:
uv run ragflow-claude-mcpMCP サーバーと同様に、stdio でリッスンします。
開発依存関係:
uv install --extra devこれで pytest + asyncio/mock/cov プラグインがインストールされます。
テスト:
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カバレッジは約 44% で、22/23 のテストが合格しています(1 つは断続的な CI の不安定さのためスキップされています)。テストはサーバーの初期化、RAGFlow API 統合、DSPy の深化、OpenAI/OpenRouter 設定ブランチ、および設定の読み込みをカバーしています。
実装ノート
取得 API は、サーバーが実際に依存している唯一の RAGFlow サーフェスです。アシスタント/チャットの依存関係はなく、サーバー側のプロンプト設定もありません。チャンクが返されるだけです。推論しやすく、デバッグも容易です。
トラブルシューティング
「Dataset not found」:
ragflow_list_datasetsを実行して、実際に何があるかを確認してください。接続エラー:
RAGFLOW_BASE_URLとRAGFLOW_API_KEYを再確認してください。サーバーが起動しない:
uv installは完了しましたか?生のチャンクが必要: それは
ragflow_retrieval_by_name/ragflow_retrievalです。セッションがスタックしている:
ragflow_list_sessionsを実行してからragflow_reset_sessionを実行してください。Cloudflare 403:
CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRETが Zero Trust アプリのアクティブなサービス・トークンと一致していることを確認してください。
既知の問題
再ランキングがアップストリームで壊れています
use_rerank=true は UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol というエラーになります。これは RAGFlow 側の欠陥です。回避策: オフのままにしてください。修正のために RAGFlow リポジトリを監視しています。
貢献
PR のみ — main は保護されています。コミットは SSH 署名されている必要があります。
フォークします。
git checkout -b feature/your-thing。変更を行い、明確なコミットメッセージを書きます。
フォークにプッシュします。
mainに対して PR を開きます。
PR は自動的に TruffleHog を実行します。キー、トークン、シークレットを含めないでください。詳細については CONTRIBUTING.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