Skip to main content
Glama
RAGFlow Claude MCP Server

RAGFlow Claude MCP Server

by norandom

RAGFlow Claude MCP 서버

RAGFlow 인스턴스를 Claude Desktop(및 기타 MCP 클라이언트)에 연결하는 소규모 MCP(Model Context Protocol) 서버입니다. RAGFlow REST API를 몇 가지 도구로 노출하여 LLM이 지식 베이스를 쿼리하고 문서 청크를 컨텍스트로 가져올 수 있도록 합니다.

이것은 제가 개인적인 R&D를 위해 작성한 개인용 소프트웨어입니다. 버그가 없을 수 없으며 코드가 깔끔하지도 않습니다. 제가 필요한 용도로는 잘 작동합니다.

기능

  • 직접 검색: RAGFlow의 /retrieval 엔드포인트에서 유사도 점수가 포함된 원시 문서 청크를 가져옵니다.

  • 다중 KB 검색: 단일 쿼리로 여러 지식 베이스를 동시에 검색할 수 있습니다.

  • DSPy 쿼리 심화: 선택적 반복 쿼리 개선(LLM을 사용하여 중간 결과를 분석하고 쿼리를 다시 작성).

  • ~~재순위 지정(Reranking)~~ — 현재 RAGFlow 측에서 작동하지 않음, 알려진 문제 참조.

  • 조정 가능한 결과 제어: page_size, similarity_threshold, top_k, 페이지 매기기.

  • 문서 필터: 데이터셋 내의 특정 문서로 결과 제한(퍼지 이름 매칭).

  • ID 대신 이름으로 데이터셋 조회(대소문자 구분 없음, 퍼지 매칭).

  • RAGFlow가 Cloudflare Zero Trust 뒤에 있을 때 인증 지원.

Related MCP server: RAGBrain MCP

설치

  1. 복제:

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

    # On macOS, install DSPy first to dodge build issues:
    pip install git+https://github.com/stanfordnlp/dspy.git
    
    uv install
  3. 구성: 샘플을 복사하고 RAGFlow 세부 정보를 입력합니다.

    cp config.json.sample config.json

    키:

    • RAGFLOW_BASE_URL: 예: http://your-ragflow-server:9380

    • RAGFLOW_API_KEY: RAGFlow API 키

    • RAGFLOW_DEFAULT_RERANK: 재순위 지정 모델(기본값 rerank-multilingual-v3.0)

    • CF_ACCESS_CLIENT_ID (선택 사항): Cloudflare Zero Trust 서비스 토큰 ID

    • CF_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 (가장 많이 사용하는 도구)

이름으로 하나 이상의 데이터셋에서 청크를 검색합니다. 유사도 점수가 포함된 원시 청크를 반환합니다.

매개변수:

  • dataset_names (필수) — 리스트, 예: ["BASF", "Quant Literature"]

  • query (필수)

  • document_name (선택 사항) — 특정 문서로 제한; 퍼지 매칭

  • top_k (선택 사항, 기본값 1024) — 벡터 후보

  • similarity_threshold (선택 사항, 기본값 0.2) — 0.0–1.0

  • page (선택 사항, 기본값 1)

  • page_size (선택 사항, 기본값 10)

  • use_rerank (선택 사항, 기본값 false) — 현재 업스트림에서 작동하지 않음, 알려진 문제 참조

  • deepening_level (선택 사항, 기본값 0) — DSPy 개선, 0–3

ragflow_retrieval

형태는 같지만 이름 대신 dataset_ids: List[str]을 사용합니다.

다중 KB 검색

한 번의 호출로 여러 지식 베이스를 검색할 수 있습니다. 임베딩 모델을 공유하는지 확인하십시오. 호환되지 않는 임베딩을 혼합하면 관련성 점수가 떨어집니다.

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

한 문서에 대한 청크(참조 포함)를 반환합니다.

  • dataset_id (필수)

  • document_id (필수)

ragflow_list_sessions

데이터셋별 활성 채팅 세션을 표시합니다. 매개변수 없음.

ragflow_list_documents_by_name

이름으로 조회하여 데이터셋의 문서를 나열합니다.

  • dataset_name (필수)

ragflow_reset_session

데이터셋의 채팅 세션을 삭제합니다.

  • dataset_id (필수)

검색 조정

검색 도구는 세 가지 노브를 사용합니다:

  • 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."

특정 문서로 제한:

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-mcp

MCP 서버가 하는 방식대로 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 테스트가 통과되었습니다(하나는 간헐적인 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 서명이 있어야 합니다.

  1. 포크하십시오.

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

  3. 변경하고 명확한 커밋 메시지를 작성하십시오.

  4. 포크로 푸시하십시오.

  5. main에 대해 PR을 여십시오.

PR은 TruffleHog를 자동으로 실행하므로 키, 토큰 또는 시크릿을 포함하지 마십시오. 자세한 내용은 CONTRIBUTING.md를 참조하십시오.

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