RAGFlow Claude MCP Server
Servidor MCP de RAGFlow para Claude
Un pequeño servidor de Model Context Protocol (MCP) que conecta Claude Desktop (y otros clientes MCP) a una instancia de RAGFlow. Expone la API REST de RAGFlow como un conjunto de herramientas para que el LLM pueda consultar bases de conocimientos y extraer fragmentos de documentos en su contexto.
Este es un software de uso personal que escribí para mi propia I+D. No está libre de errores y el código no es elegante. Funciona para lo que necesito.
Qué hace
Recuperación directa: extrae fragmentos de documentos sin procesar con puntuaciones de similitud desde el endpoint
/retrievalde RAGFlow.Búsqueda en múltiples KB: una sola consulta puede acceder a varias bases de conocimientos a la vez.
Profundización de consultas con DSPy: refinamiento iterativo de consultas opcional (utiliza un LLM para analizar resultados intermedios y reescribir la consulta).
~~Reclasificación (Reranking)~~ — actualmente roto en el lado de RAGFlow, ver Problemas conocidos.
Control de resultados ajustable:
page_size,similarity_threshold,top_k, paginación.Filtro de documentos: limita los resultados a un documento dentro de un conjunto de datos (coincidencia difusa de nombres).
Búsqueda de conjuntos de datos por nombre (sin distinción entre mayúsculas y minúsculas, difusa) en lugar de por ID.
Autenticación Cloudflare Zero Trust cuando su RAGFlow se encuentra detrás de ella.
Related MCP server: RAGBrain MCP
Instalación
Clonar:
git clone https://github.com/norandom/ragflow-claude-desktop-local-mcp cd ragflow-claude-desktop-local-mcpInstalar:
# On macOS, install DSPy first to dodge build issues: pip install git+https://github.com/stanfordnlp/dspy.git uv installConfigurar: copie la muestra y rellene sus detalles de RAGFlow.
cp config.json.sample config.jsonClaves:
RAGFLOW_BASE_URL: ej.http://your-ragflow-server:9380RAGFLOW_API_KEY: su clave API de RAGFlowRAGFLOW_DEFAULT_RERANK: modelo de reclasificación (por defectorerank-multilingual-v3.0)CF_ACCESS_CLIENT_ID(opcional): ID de token de servicio de Cloudflare Zero TrustCF_ACCESS_CLIENT_SECRET(opcional): secreto de token de servicio de Cloudflare Zero TrustDSPY_MODEL: LM de DSPy (por defectoopenai/gpt-4o-mini)OPENAI_API_KEY: necesario para la profundización con DSPy
Cloudflare Zero Trust
Si su RAGFlow está detrás de Cloudflare Zero Trust, obtenga un token de servicio del panel de control y añádalo a config.json:
{
"CF_ACCESS_CLIENT_ID": "your-client-id.access",
"CF_ACCESS_CLIENT_SECRET": "your-client-secret"
}Cuando ambos están configurados, cada solicitud de API se envía con los encabezados CF-Access-Client-Id y CF-Access-Client-Secret. No se requiere ningún cambio en el código.
Configuración de Claude Desktop
{
"mcpServers": {
"ragflow": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/ragflow-claude-desktop-local-mcp",
"ragflow-claude-mcp"
]
}
}
}Herramientas
ragflow_retrieval_by_name (la que más uso)
Recupera fragmentos a través de uno o más conjuntos de datos por nombre. Devuelve fragmentos sin procesar con puntuaciones de similitud.
Parámetros:
dataset_names(obligatorio) — lista, ej.["BASF", "Quant Literature"]query(obligatorio)document_name(opcional) — restringir a un documento; coincidencia difusatop_k(opcional, por defecto 1024) — candidatos vectorialessimilarity_threshold(opcional, por defecto 0.2) — 0.0–1.0page(opcional, por defecto 1)page_size(opcional, por defecto 10)use_rerank(opcional, por defecto false) — actualmente roto en el origen, ver Problemas conocidosdeepening_level(opcional, por defecto 0) — refinamiento con DSPy, 0–3
ragflow_retrieval
La misma forma, pero toma dataset_ids: List[str] en lugar de nombres.
Búsqueda en múltiples KB
Puede buscar en varias bases de conocimientos en una sola llamada. Asegúrese de que compartan un modelo de incrustación (embedding): mezclar incrustaciones incompatibles arruinará las puntuaciones de relevancia.
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
Enumera todas las bases de conocimientos en su instancia de RAGFlow. Sin parámetros. Recorre todas las páginas internamente.
ragflow_list_documents
Enumera los documentos en un conjunto de datos. Recorre todas las páginas.
dataset_id(obligatorio)
ragflow_get_chunks
Devuelve fragmentos (con referencias) para un documento.
dataset_id(obligatorio)document_id(obligatorio)
ragflow_list_sessions
Muestra las sesiones de chat activas por conjunto de datos. Sin parámetros.
ragflow_list_documents_by_name
Enumera los documentos en un conjunto de datos, buscados por nombre.
dataset_name(obligatorio)
ragflow_reset_session
Elimina la sesión de chat para un conjunto de datos.
dataset_id(obligatorio)
Ajuste de la recuperación
Las herramientas de recuperación tienen tres controles:
page_size— fragmentos por página (por defecto 10).similarity_threshold— descarta fragmentos por debajo de esta puntuación (por defecto 0.2).top_k— tamaño del grupo para la búsqueda vectorial antes del filtrado (por defecto 1024).
Algunos puntos de partida que me funcionan:
Recuperación más amplia:
page_size=15,similarity_threshold=0.15.Precisión estricta:
page_size=5,similarity_threshold=0.4.Investigación profunda:
page_size=20,similarity_threshold=0.1,deepening_level=1.Consultas difíciles:
deepening_level=2.Velocidad: mantenga
deepening_level=0y omita la reclasificación.
Ejemplos
Recuperación básica por nombre:
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."Restringir a un documento:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], document_name "annual_report_2023", and query "What were the key financial highlights for 2023?"Los nombres de los documentos coinciden de forma difusa: "annual" coincidirá con annual_report_2023.pdf y annual_report_2024.pdf. Cuando coinciden varios, el servidor elige el más reciente y enumera las alternativas en los metadatos de respuesta.
Profundización con DSPy para una consulta complicada:
Use ragflow_retrieval_by_name with dataset_names ["Quant Literature"], query "what is a volatility clock", deepening_level 2.Varias páginas:
Use ragflow_retrieval_by_name with dataset_names ["BASF"], query "BASF business segments", page_size 10, page 2.Listar lo que está disponible:
Use ragflow_list_datasets.Use ragflow_list_documents_by_name with dataset_name "BASF".Extraer fragmentos específicos:
Use ragflow_get_chunks with dataset_id "43066ee0599411f089787a39c10de57b" and document_id "d74a1c105a3311f09fc94a0fcd8b7722".Prompts más grandes
Algunos ejemplos de cómo lo manejo desde Claude Desktop.
Análisis financiero profundo:
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.Investigación multilingüe:
Use ragflow_retrieval_by_name with dataset_names ["BASF"],
query "Was sind die wichtigsten Geschäftsbereiche von BASF?",
deepening_level 2.DSPy detecta el idioma de la consulta y lo refina en consecuencia. Lo he usado para consultas en alemán, inglés y en idiomas mixtos. Funciona siempre que los documentos subyacentes tengan contenido en esos idiomas.
Investigación filtrada por documento:
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".Consulta entre KB:
Use ragflow_retrieval_by_name with dataset_names ["BASF", "Industry Reports"],
query "chemical industry sustainability benchmarks",
page_size 12, deepening_level 1.Cómo funciona la profundización de DSPy
deepening_level ejecuta un bucle de refinamiento impulsado por LLM sobre la recuperación:
0: sin profundización (por defecto).
1: una pasada de refinamiento.
2: dos pasadas con análisis de brechas.
3: tres o más pasadas más fusión de resultados.
Cada pasada: realizar la búsqueda, resumir los mejores resultados, preguntar al LLM qué falta, generar una nueva consulta, ejecutarla. Los metadatos de respuesta incluyen la consulta original, cada consulta refinada y el razonamiento en cada paso.
DSPy necesita:
DSPY_MODEL—openai/gpt-4o-minifunciona bienOPENAI_API_KEY
Reclasificación (actualmente rota)
Cuando funciona, la reclasificación reemplaza la puntuación de coseno vectorial con la puntuación del modelo de reclasificación (típicamente un 10-30% mejor de relevancia en mi experiencia). RAGFlow tiene un error conocido en este momento donde use_rerank=true produce:
UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol
Así que deje use_rerank=false hasta que se solucione el problema en el origen. La recuperación vectorial estándar funciona normalmente.
Cómo funciona la búsqueda de conjuntos de datos
Coincidencia de nombres sin distinción entre mayúsculas y minúsculas.
Coincidencia difusa para nombres parciales.
Los conjuntos de datos se almacenan en caché para la búsqueda de nombres; los fallos de caché activan una actualización.
Si la búsqueda falla, el error incluye los nombres de los conjuntos de datos disponibles para que sepa qué había realmente allí.
Coincidencia de documentos
Cuando pasa document_name:
La coincidencia exacta gana, luego "comienza con", luego "contiene", luego parcial.
En caso de empate, gana el documento actualizado más recientemente.
Los nombres que contienen
2024,2023,latest,currentonewobtienen una pequeña bonificación de puntuación.Todas las coincidencias se devuelven en los metadatos de respuesta para que pueda volver a emitir con un nombre más específico.
Manejo de errores
Mensajes de error razonables para: errores de API, conjuntos de datos faltantes, RAGFlow inalcanzable, sesiones rotas, entrada no válida y problemas de configuración. Los valores sensibles se ocultan en los registros.
Variables de entorno
RAGFLOW_BASE_URL— anula el archivo de configuración. Por defecto en el código:http://192.168.122.93:9380(que es mi instancia local).RAGFLOW_API_KEY— obligatorio.
Desarrollo
Ejecute el servidor directamente:
uv run ragflow-claude-mcpEscucha en stdio, como hacen los servidores MCP.
Dependencias de desarrollo:
uv install --extra devEso obtiene pytest + los complementos asyncio/mock/cov.
Pruebas:
uv run pytest
uv run pytest --cov=src --cov-report=html --cov-report=term
uv run pytest tests/test_server.py
uv run pytest -vLa cobertura es de alrededor del 44% con 22/23 pruebas pasando (una se omite debido a un fallo intermitente de CI). Las pruebas cubren la inicialización del servidor, la integración de la API de RAGFlow, la profundización de DSPy, las ramas de configuración de OpenAI/OpenRouter y la carga de configuración.
Notas de implementación
La API de recuperación es la única superficie de RAGFlow en la que realmente se basa el servidor. Sin dependencias de asistente/chat, sin configuración de prompt del lado del servidor: solo fragmentos de vuelta. Más fácil de razonar, más fácil de depurar.
Solución de problemas
"Dataset not found": ejecute
ragflow_list_datasetspara ver qué hay realmente allí.Errores de conexión: verifique
RAGFLOW_BASE_URLyRAGFLOW_API_KEY.El servidor no arranca: ¿terminó realmente
uv install?Necesita fragmentos sin procesar: eso es
ragflow_retrieval_by_name/ragflow_retrieval.Sesión bloqueada:
ragflow_list_sessionsy luegoragflow_reset_session.403 de Cloudflare: confirme que
CF_ACCESS_CLIENT_ID/CF_ACCESS_CLIENT_SECRETcoinciden con un token de servicio activo en la aplicación Zero Trust.
Problemas conocidos
La reclasificación está rota en el origen
use_rerank=true da error con UnsupportedProtocol: Request URL is missing an 'http://' or 'https://' protocol. Este es un defecto del lado de RAGFlow. Solución: déjelo desactivado. Estoy atento al repositorio de RAGFlow para una solución.
Contribución
Solo PRs: main está protegido. Los commits deben estar firmados con SSH.
Bifurcar (Fork).
git checkout -b feature/your-thing.Realice el cambio, escriba un mensaje de commit claro.
Envíe a su bifurcación.
Abra un PR contra
main.
Los PRs ejecutan TruffleHog automáticamente: no incluya claves, tokens o secretos. Consulte CONTRIBUTING.md para la versión más larga.
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