Local Rag MCP Server

MCP搜索检索

提供方 efn-2101

搜索检索 stdio · 本地进程 API Key 社区 / 第三方 Cline
查看接入方式

一个能够在本地PC或服务器上通过自然语言搜索共享文件夹中文档的MCP服务器,支持多种文件格式的自动转换和向量化索引,提供基于Ollama嵌入模型的语义搜索(RAG)功能。

一句话选型结论

按资料字段整理

Local Rag MCP Server 属于搜索检索类 MCP 服务器,stdio · 本地进程,API Key,可直接接入 Cline,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类搜索检索 传输方式stdio · 本地进程 鉴权API Key 部署方式本地部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 7 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

搜索检索
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量7暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

文档搜索Python本地部署语义搜索RAG文件管理自然语言搜索文档转换

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
python -m venv venv

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 7 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
联网搜索取证

让模型查最新资料并给出出处。

资料聚合

把一个主题的网页、文档集中抓回来整理。

情报与竞品检索

按关键词持续检索行业动态和竞品信息。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 7 个工具,职责相对集中,接入后不容易误操作。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Cline,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在搜索检索场景里让模型直接调用外部能力的人。
  • 已经在用 Cline 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Local Rag MCP Server当前 7 stdio · 本地进程 本地部署 有 2026-05-17
Brave Search 433812ff 2 未标注 未标注 无 2026-05-17
Sequentialthinking 1 SSE · 服务端推送 远程部署 有 2026-05-18
Baidu Netdisk 未标注 未标注 未标注 无 2026-05-17
ragflow 未标注 stdio · 本地进程 本地部署 有 2026-04-11
mindsdb (430e18) 未标注 未标注 未标注 有 2026-05-17

服务器档案

搜索检索
字段来自项目仓库与公开索引,中文说明由本站标注
提供方efn-2101上游标注的维护方 efn-2101
分类搜索检索本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式API Key远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

37.1 KB
来自项目仓库与上游目录的原文,未做删改

Local RAG MCP Server

ローカル PC またはサーバー上の共有フォルダにある文書ファイルを AI から自然言語で検索できる MCP (Model Context Protocol) サーバー です。

PDF・Word・Excel・PowerPoint・画像・ソースコードなど多様なファイルを自動変換してベクトルインデックス化し、Ollama の埋め込みモデルを使用したセマンティック検索 (RAG) を提供します。CLINE などの MCP 対応クライアントから利用できます。

> 📋 更新履歴は CHANGELOG.md を参照してください。

> [!NOTE]
> 【重要】Ollama v0.17.x系における glm-ocr の不具合について
> かつて Ollama v0.17.0 〜 v0.17.5 までのバージョンにおいて、glm-ocr モデルを使用した際の OCR 結果が異常(空白等)になる問題が発生していましたが、Ollama v0.17.6 以降でこの問題は修正されています。
>
> 現在最新の Ollama を使用していれば問題ありませんが、もし v0.17.0 〜 v0.17.5 をお使いの場合は、v0.17.6 以上へのアップデートを推奨します。

機能一覧

機能 説明
文書変換 PDF・DOCX・XLSX・PPTX・画像 → Markdown 変換(OCR対応)
ハイブリッド検索 ベクトル検索 (Dense) と BM25 (Sparse) を組み合わせた高精度検索
リランキング FlashRank による検索結果の再評価・最適化
アクセス制御 (ACL) API キーによるルートフォルダ単位の検索権限管理
差分同期 更新ファイルのみ再インデックス(mtime + 内容ハッシュ管理)
ハッシュベースOCRスキップ 内容が変わっていないファイルのOCR処理をスキップ
コンテキスト制限 巨大ドキュメント(1MB超)の自動圧縮・LLMコンテキスト上限を超えない制御
SSE / Stdio 両対応 CLINE (SSE) や stdio MCP クライアントどちらでも利用可能

アーキテクチャ概要```mermaid

flowchart TD
subgraph UserSide["👤 ユーザー側"]
Client["🖥️ MCPクライアント<br/>(CLINE 等)"]
end

subgraph ServerSide[&quot;⚙️ サーバー側 (Local RAG MCP Server)&quot;]
    Server[&quot;server.py&lt;br/&gt;MCPサーバー&lt;br/&gt;(SSE / stdio)&quot;]
    RAG[&quot;rag_engine.py&lt;br/&gt;RAGエンジン&quot;]
    Chroma[(&quot;ChromaDB&lt;br/&gt;ベクトルDB&lt;br/&gt;(Dense検索)&quot;)]
    BM25[(&quot;BM25インデックス&lt;br/&gt;(Sparse検索)&quot;)]
    FlashRank[&quot;FlashRank&lt;br/&gt;リランキングモデル&quot;]
    ModelCache[(&quot;models/flashrank_cache/&lt;br/&gt;モデルキャッシュ&quot;)]
    Ollama_Embed[&quot;Ollama&lt;br/&gt;埋め込みモデル&quot;]
    Converter[&quot;file_converter.py&lt;br/&gt;文書変換エンジン&quot;]
    OCR_Ollama[&quot;Ollama&lt;br/&gt;glm-ocr (OCR)&quot;]
    OCR_Paddle[&quot;PaddleOCR&quot;]
    UpdateIdx[&quot;update_index.py&lt;br/&gt;インデックス更新スクリプト&lt;br/&gt;(手動 / cron / タスクスケジューラー)&quot;]
    Docs[&quot;📁 ソース文書&lt;br/&gt;(PDF / DOCX / 画像 等)&quot;]
end

Client &lt;--&gt;|&quot;MCP Protocol&lt;br/&gt;(検索 / ツール実行 / 応答)&quot;| Server
Server &lt;--&gt; RAG
RAG &lt;--&gt; Chroma
RAG &lt;--&gt; BM25
RAG &lt;--&gt; Ollama_Embed
RAG &lt;--&gt; FlashRank
FlashRank &lt;--&gt; ModelCache
RAG &lt;--&gt; Converter
Converter &lt;--&gt;|&quot;ocr_engine&quot;| OCR_Ollama
Converter &lt;--&gt;|&quot;ocr_engine&quot;| OCR_Paddle
Docs --&gt; RAG
UpdateIdx --&gt;|&quot;差分 / フル再構築&quot;| RAG
RAG --&gt;|&quot;ハイブリッド検索結果&quot;| FlashRank
FlashRank --&gt;|&quot;リランキング済み結果&quot;| Server

# 🔧 管理者向けガイド

## 1. 必要環境

- Python 3.10 以上
- Ollama(ローカル実行)
  - 埋め込みモデル(例: `nomic-embed-text-v2-moe:latest`)
  - OCR モデル(例: `glm-ocr:latest`)

## 2. インストール```bash
# 1. リポジトリを任意のフォルダに配置

# 2. 仮想環境を作成して有効化
python -m venv venv
venv\Scripts\activate        # Windows
# source venv/bin/activate   # Linux / macOS

# 3. 依存パッケージをインストール
pip install -r requirements.txt

2.1 OCRエンジンの選択

本システムは2種類のOCRエンジンをサポートしています:

OCRエンジン 特徴 インストール
Ollama glm-ocr(デフォルト) Ollamaサーバー経由でOCR実行。追加インストール不要。GPUはOllama側で管理。 なし(Ollamaにglm-ocrモデルをプルするのみ)
PaddleOCR(オプショナル) ローカル実行のOCRライブラリ。Ollamaに依存せず動作可能。 別途インストール必要

Ollama glm-ocrを使用する場合(デフォルト)```bash

Ollamaにglm-ocrモデルをプル

ollama pull glm-ocr:latest


`config.json`で以下のように設定:```json
{
  &quot;ocr_engine&quot;: &quot;ollama&quot;,
  &quot;ocr_model&quot;: &quot;glm-ocr:latest&quot;
}

PaddleOCRを使用する場合(オプショナル)

PaddleOCRはオプショナルな依存関係です。使用する場合は以下の手順でインストールしてください。

CPU版のインストール(推奨):```bash
pip install paddlepaddle paddleocr


**GPU版のインストール(上級者向け)**:```bash
pip install paddlepaddle-gpu paddleocr

> [!WARNING]
> GPU版の導入は特定のDLL (cudnn64_8.dll, zlibwapi.dll) の手動配置が求められるため上級者向けです。どうしてもGPU版を利用したい場合は、PADDLE_GPU_SETUP.md の手順に従って個別にセットアップを行ってください。

config.jsonで以下のように設定:```json
{
"ocr_engine": "paddleocr",
"paddleocr_use_gpu": false
}


&gt; [!TIP]
&gt; PaddleOCRがインストールされていない状態で`ocr_engine: &quot;paddleocr&quot;`を設定した場合、自動的にOllama glm-ocrにフォールバックします。

## オフライン環境へのインストール

ネットワークに接続されていないUbuntu端末へのインストール方法を提供しています。

### Dockerイメージ方式(推奨)

Dockerイメージを使用して、環境を完全にパッケージングできます。```bash
# Windows側(オンライン環境)
.\scripts\export-docker-image.ps1 -IncludeModels

# Ubuntu側(オフライン環境)
./scripts/import-docker-image.sh
docker-compose up -d

自己完結型パッケージ方式

Python環境が不要なスタンドアロンバイナリを生成できます。```bash

ビルド

python build-standalone.py --clean


詳細な手順は docs/OFFLINE_INSTALL.md を参照してください。

### Docker環境でのユーティリティ実行

Docker環境では、以下のコマンドでユーティリティを実行できます:```bash
# インデックスの手動更新
docker-compose exec mcp-server python update_index.py

# サーバーの停止(通常は docker-compose stop を使用)
docker-compose exec mcp-server python stop.py

3. 初期設定

config.json

config.json を自分の環境に合わせて編集してください。```json
{
"source_docs_dir": "C:\path\to\your\documents",
"docs_dir": "converted_docs",
"embedding_model": "nomic-embed-text-v2-moe:latest",
"ocr_engine": "paddleocr",
"ocr_model": "glm-ocr:latest",
"extra_text_extensions": [".conf", ".ini", ".env", ".log"],
"paddleocr_use_gpu": false,
"ollama_base_url": "http://localhost:11434",
"db_dir": "./chroma_db",
"collection_name": "mcp_rag_collection",
"search_settings": {
"hybrid_search_enabled": true,
"reranking_enabled": true,
"flashrank_model": "ms-marco-MultiBERT-L-12",
"flashrank_cache_dir": "models/flashrank_cache",
"flashrank_offline_mode": false
},
"context_management": {
"detail_level": "auto",
"max_context_tokens": 128000,
"max_document_tokens": 12000,
"max_search_result_tokens": 8000,
"summary_model": null,
"ollama_base_url": null
}
}


| キー | 説明 |
|------|------|
| `source_docs_dir` | 元文書フォルダの**絶対パスまたは相対パス**(server.py からの相対) |
| `docs_dir` | 変換済み Markdown の保存先(相対パス) |
| `embedding_model` | Ollama の埋め込みモデル名 |
| `ocr_engine` | OCRエンジン(`ollama` または `paddleocr`) |
| `ocr_model` | PDF/画像の OCR に使う Ollama モデル名 (ocr_engine が ollama の場合) |
| `extra_text_extensions` | テキストとしてそのまま読み込む追加の拡張子リスト(例: `[&quot;.conf&quot;, &quot;.env&quot;]`) |
| `paddleocr_use_gpu` | PaddleOCR実行時にGPUを使用するかどうか (`true` または `false`) |
| `ollama_base_url` | Ollama の API エンドポイント |
| `db_dir` | ChromaDB の保存先(相対パス) |
| `collection_name` | ChromaDB コレクション名 |
| `search_settings` | 検索エンジンに関する詳細設定(以下参照) |
| `context_management` | 巨大ドキュメントのコンテキスト制限設定(以下参照) |

### search_settings の詳細

| パラメータ | 説明 |
|------------|------|
| `hybrid_search_enabled` | ハイブリッド検索(ベクトル検索 + BM25)を有効にするか (`true`/`false`) |
| `reranking_enabled` | FlashRank によるリランキングを有効にするか (`true`/`false`) |
| `flashrank_model` | 使用する FlashRank モデル名 |
| `flashrank_cache_dir` | FlashRank モデルの保存先ディレクトリ |
| `flashrank_offline_mode` | オフラインモードを有効にするか (`true`/`false`) |

### context_management の詳細

| パラメータ | 説明 |
|------------|------|
| `detail_level` | ドキュメント詳細度: `&quot;auto&quot;`(デフォルト、上限超過時のみ圧縮) / `&quot;summary&quot;`(常に圧縮) / `&quot;full&quot;`(常に全文) |
| `max_context_tokens` | LLMのコンテキスト上限トークン数(デフォルト: 128000) |
| `max_document_tokens` | `get_document_content` の最大返却トークン数(デフォルト: 12000) |
| `max_search_result_tokens` | `search_documents` の最大返却トークン数(デフォルト: 8000) |
| `summary_model` | LLM要約用のOllamaモデル名(オプション。`null` の場合は構造ベース圧縮のみ使用) |
| `ollama_base_url` | 要約専用の別OllamaサーバーURL(オプション。`null` の場合はデフォルトの `ollama_base_url` を使用) |

#### 巨大ドキュメント(1MB超)の扱いについて

本サーバーは **1MB超の単一Markdownファイル** など、巨大ドキュメントに対して自動的にコンテキスト制限を適用します。

**仕組み:**
1. `get_document_content` や `search_documents` の返却時に、トークン数を自動カウント
2. 設定された上限(`max_document_tokens` / `max_search_result_tokens`)を超える場合、Markdownの見出し構造を尊重して段階的に圧縮
3. 圧縮時は「先頭文 + 重要キーワード文 + 末尾文」を残し、省略部分は `get_document_content(path=..., section=...)` で詳細取得可能と明示

**後方互換性:**
- `config.json` に `context_management` が未設定の場合、`detail_level: &quot;auto&quot;` で動作(上限内なら全文返却、超過時のみ圧縮)
- 通常サイズのドキュメント(数KB〜数百KB)は従来通り全文返却

#### FlashRank オフライン運用について

インターネット接続がない環境でリランキング機能を使用する場合は、以下の手順でセットアップを行ってください。

**推奨モデル:**
- デフォルト: `ms-marco-MultiBERT-L-12`(軽量・高速)

**フォルダ構成:**```
models/
└── flashrank_cache/
    └── ms-marco-MultiBERT-L-12/
        ├── tokenizer.json
        ├── tokenizer_config.json
        ├── special_tokens_map.json
        └── *.onnx (モデルファイル)

オフラインモードの設定手順:

  1. モデルのダウンロード(オンライン環境で実行)
    - インターネット接続のある環境でサーバーを起動し、初回の検索を実行すると自動的にモデルがダウンロードされます
    - または、手動でモデルファイルを上記フォルダ構成で配置します

  2. オフラインモードの有効化
    - config.json で flashrank_offline_mode: true を設定します
    - これにより、インターネット接続を試みずにローカルのモデルファイルを使用します

  3. 動作確認
    - オフライン環境でサーバーを起動し、検索が正常に動作することを確認してください

ドキュメントフォルダの構成

本サーバーの基本的な運用思想は、既存の共有フォルダをドキュメントフォルダ(source_docs_dir)として設定することです。ユーザーは普段通りに共有フォルダへファイルを追加・更新・削除できます。セキュリティは OS(Windows / Linux)のフォルダアクセス権で管理します。

source_docs_dir 直下に ルートフォルダ を作成し、その中に文書を格納してください。

> [!IMPORTANT]
> ルートフォルダ名は英語を推奨します。
> 日本語フォルダ名も使用できますが、CLINE からデフォルト検索スコープを設定する際に URL への記載が必要になります。詳細は「ユーザー向け:CLINE への接続設定」を参照してください。```
documents/ ← source_docs_dir
├── Public/ ← ルートフォルダ(誰でもアクセス可)
│ └── manual.pdf
├── Group A/ ← グループA専用
│ └── design_spec.docx
└── Group B/ ← グループB専用
└── report.xlsx


### acl.json(検索アクセス権限の設定)

`acl.json` は **「API キーとルートフォルダのアクセス権限のマッピング」** を管理します。フォルダへの OS 権限とは独立した検索権限の設定です。```json
{
  &quot;_comment&quot;: &quot;MCPサーバーのグループアクセス制御設定ファイル。&quot;,
  &quot;_default&quot;: {
    &quot;name&quot;: &quot;Public&quot;,
    &quot;allowed_roots&quot;: [&quot;Public&quot;]
  },
  &quot;your-api-key-here&quot;: {
    &quot;name&quot;: &quot;Group A&quot;,
    &quot;allowed_roots&quot;: [&quot;Group A&quot;, &quot;Public&quot;]
  }
}
エントリ 説明
_default API キー未設定で接続した場合に適用される権限
&quot;キー文字列&quot; そのキーを提示したクライアントが検索可能なルートフォルダを定義

> [!TIP]
> 複数の API キーを指定可能
> x-api-key ヘッダーや URL クエリパラメータには、カンマ区切りで複数の API キー(例: key1,key2)を指定できます。この場合、指定されたすべてのキーに紐づく allowed_roots がマージ(和集合)され、複数のグループの文書を横断的に検索できるようになります。

> API キーは推測されにくいランダムな文字列を使用してください(例: openssl rand -hex 32 で生成)。

注意: acl.json の変更はサーバー再起動まで反映されません。

3.4. 初回インデックスの作成

サーバーを初めて起動する前に、ドキュメントのインデックスを作成(データベース登録)する必要があります。サーバーの起動だけでは自動的にインデックスは作成されません。

以下のコマンドを実行して、ドキュメントのインデックスを作成してください。```bash

ドキュメントの同期(初回・差分更新)

python update_index.py


初回はドキュメントの量に応じて時間がかかる場合があります(特に OCR が必要な場合)。この処理が完了してから、次の「4. サーバーの起動・停止」へ進んでください。

## 4. サーバーの起動・停止

### 起動(SSE モード・CLINE などの HTTP クライアント向け)```bash
python server.py --transport sse --port 8000

起動(stdio モード・MCP 標準入出力クライアント向け)```bash

python server.py --transport stdio


### 停止```bash
python stop.py

または、サーバーを起動したターミナルで Ctrl+C を押してください。

5. バックグラウンド常駐(本番運用)

Ubuntu / Linux(systemd)

systemd サービスとして登録すると、OS 起動時に自動起動・クラッシュ時に自動再起動されます。

サービスファイルの作成```bash

sudo nano /etc/systemd/system/local-rag-mcp.service


以下の内容を貼り付けてください(パスは実際の環境に合わせてください)。```ini
[Unit]
Description=Local RAG MCP Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username/local-rag-mcp-server
ExecStart=/home/your-username/local-rag-mcp-server/venv/bin/python server.py --transport sse --port 8000
Restart=on-failure
RestartSec=5
StandardOutput=append:/home/your-username/local-rag-mcp-server/server.log
StandardError=append:/home/your-username/local-rag-mcp-server/server.log

[Install]
WantedBy=multi-user.target

サービスの有効化と起動```bash

sudo systemctl daemon-reload
sudo systemctl enable local-rag-mcp # OS起動時に自動起動
sudo systemctl start local-rag-mcp # 今すぐ起動
sudo systemctl status local-rag-mcp # 状態確認


#### 操作コマンド```bash
sudo systemctl stop local-rag-mcp     # 停止
sudo systemctl restart local-rag-mcp  # 再起動
journalctl -u local-rag-mcp -f        # リアルタイムログ確認

Windows(タスクスケジューラー)

PowerShell で以下を実行します(管理者権限で実行してください)。```powershell

サーバーをログイン時に自動起動

$action = New-ScheduledTaskAction -Execute &quot;D:\tools\local-rag-mcp-servr\venv\Scripts\python.exe&quot;
-Argument "server.py --transport sse --port 8000" `
-WorkingDirectory "D:\tools\local-rag-mcp-servr"

$trigger = New-ScheduledTaskTrigger -AtLogOn

Register-ScheduledTask -TaskName "LocalRagMCPServer" -Action $action -Trigger $trigger
-RunLevel Highest -Force


## 6. インデックスの自動更新

インデックス更新はサーバーを停止せずに実行できます。深夜など負荷の低い時間帯に自動実行することを推奨します。

&gt; **補足**: インデックス更新中もサーバーはリクエストを受け付け続けます。更新完了後に新しいドキュメントが検索対象になります。

### 手動更新```bash
# 差分更新(通常はこちら)
python update_index.py

# 強制フル再構築
python update_index.py --force

Ubuntu / Linux(cron で毎日深夜2時に自動実行)```bash

crontab -e


以下の行を追加します。```cron
0 2 * * * cd /home/your-username/local-rag-mcp-servr &amp;&amp; ./venv/bin/python update_index.py &gt;&gt; server.log 2&gt;&amp;1

Windows(タスクスケジューラーで毎日深夜2時に自動実行)```powershell

$action2 = New-ScheduledTaskAction -Execute &quot;D:\tools\local-rag-mcp-servr\venv\Scripts\python.exe&quot;
-Argument "update_index.py" `
-WorkingDirectory "D:\tools\local-rag-mcp-servr"

$trigger2 = New-ScheduledTaskTrigger -Daily -At "02:00"

Register-ScheduledTask -TaskName "LocalRagIndexUpdate" -Action $action2 -Trigger $trigger2
-RunLevel Highest -Force


### 6.1 ハッシュベースOCRスキップと .source_hashes.json の仕様

OCR処理は時間がかかるため、本システムでは `.source_hashes.json` を用いて元ファイルの内容に変更がない(ハッシュ値が同一)場合はOCR処理を自動的にスキップします。

#### `.source_hashes.json` の仕様と生成場所

- **自動生成(通常運用時)**
  `update_index.py` などによるインデックス更新時、RAGエンジンが各ドキュメントのハッシュ値を計算し、`config.json` で指定した `db_dir`(デフォルトは `chroma_db`)直下の `.source_hashes.json` に自動保存・更新します。

- **手動生成(移行用)**
  すでに Markdown に変換済みの環境において、次回以降の不要なOCR処理を避けるため、事前にハッシュファイルのみを一括生成することができます。```bash
  python _generate_source_hashes.py
  ```

- **生成場所の整合性**
  自動生成(`update_index.py`)の場合も、手動生成(`_generate_source_hashes.py`)の場合も、**全く同じ場所(`db_dir` 配下の `.source_hashes.json`)** に生成されます。そのため手動生成を行っても、ソースコードからは正常に参照・比較が行われ、OCRスキップが正しく機能します。

## 7. ファイル監視による自動インデックス更新(上級者向け)

`file_watcher.py` は `watchdog` ライブラリを使ってソースフォルダを常時監視し、ファイルの追加・更新・削除・移動を検知すると **即座にインデックスを更新**するスクリプトです。

### 起動方法```bash
# サーバーとは別のターミナルで起動
python file_watcher.py

⚠️ リスクと注意事項

> [!WARNING]
> file_watcher.py の使用には以下のリスクがあります。十分に理解した上でご利用ください。

リスク 説明
高負荷 ファイルが頻繁に更新される環境では OCR / 埋め込み処理が連続して走り続け、CPU・メモリを大量消費します
DB競合 update_index.py や CLINE 経由の update_index ツールと同時に実行すると、ChromaDB への書き込みが競合する可能性があります
誤削除の伝播 ファイルの誤削除をそのまま検知してインデックスからも即座に削除します。元に戻すにはファイルを復元後に update_index.py の再実行が必要です
プロセス管理 stop.py は server.py のみを停止します。file_watcher.py は別途 Ctrl+C で停止してください

推奨運用

  • 更新頻度が低い環境: update_index.py の定期実行(cron / タスクスケジューラー)を推奨します
  • リアルタイム反映が必要な環境: file_watcher.py の使用を検討できますが、上記リスクを踏まえた上でご利用ください

8. トラブルシューティング

Ollama に接続できない

  • Ollama が起動しているか確認: ollama list
  • config.json の ollama_base_url が正しいか確認

ChromaDB の初期化エラー

データベースが破損している場合は自動的に再作成されます。手動で削除したい場合は chroma_db/ フォルダを削除してください。

PDF の文字が認識されない / OCR が空白出力になる

画像型 PDF の場合は OCR モデルが使用されます。config.json の ocr_model に適切なマルチモーダルモデルを指定してください。

Ollama v0.17.x で glm-ocr を使用している場合

> [!NOTE]
> Ollama v0.17.0 〜 v0.17.5 において glm-ocr モデルに非互換の不具合が確認されていましたが、この問題は Ollama v0.17.6 以降で修正されました。

対処法:
- Ollama のバージョンを v0.17.6 以上にアップデートしてください。
- アップデートが困難な場合は、OCR エンジンを &quot;paddleocr&quot; に切り替えるか、Ollama を v0.16.3 にダウングレードしてください。

なお、file_converter.py は OCR 出力が明らかに異常な場合(空文字・極端に短い出力・同一文字の繰り返しなど)を自動検出し、OCR 失敗として空のテキストを返すよう対応しています。ログに OCR validation failed: のメッセージが出た場合は、Ollama のアップデートをご検討ください。

バックスラッシュパスのデータが残っている

Windows 環境の旧データが残っている場合は以下を実行してください。```bash
python _cleanup_db.py


### インデックスロックエラー

同時に複数のインデックス更新が走った場合に発生します。しばらく待ってから再試行してください。

---

# 👤 ユーザー向けガイド

## CLINE への接続設定

管理者から提供された URL・API キーを CLINE の MCP サーバー設定に追加してください。

### stdio モード(ローカル実行・推奨)

サーバーをローカルで直接起動する場合は `stdio` モードを使用します。SSEモードと異なり、HTTPサーバーを起動する必要がなく、セキュリティ的にも安全です。```json
{
  &quot;mcpServers&quot;: {
    &quot;local-rag&quot;: {
      &quot;command&quot;: &quot;python&quot;,
      &quot;args&quot;: [&quot;server.py&quot;, &quot;--transport&quot;, &quot;stdio&quot;],
      &quot;cwd&quot;: &quot;D:\\tools\\local-rag-mcp-server&quot;,
      &quot;env&quot;: {
        &quot;MCP_API_KEY&quot;: &quot;your-api-key-here&quot;,
        &quot;DEFAULT_ROOTS&quot;: &quot;Group A&quot;,
        &quot;DEFAULT_CATEGORIES&quot;: &quot;&quot;
      }
    }
  }
}
環境変数 説明
MCP_API_KEY acl.json に定義した API キー
DEFAULT_ROOTS デフォルトで検索するルートフォルダ(カンマ区切りで複数指定可)
DEFAULT_CATEGORIES デフォルトで検索するサブフォルダ(カンマ区切りで複数指定可)

> [!TIP]
> Windowsパスを指定する場合、環境変数では D:/tools/documents のようにフォワードスラッシュを使用するか、D:\\tools\\documents のようにバックスラッシュを2つ重ねてください。本サーバーは自動的にフォワードスラッシュに正規化します。

SSE モード(HTTP経由)

SSEモードを使用する場合は、以下のように URL とヘッダーを設定します。

フォルダ名が英語の場合(推奨)

x-roots / x-categories ヘッダーにフォルダ名を直接記載できます。```json
{
"mcpServers": {
"local-rag": {
"url": "http://localhost:8000/sse",
"headers": {
"x-api-key": "your-api-key-here",
"x-roots": "Group A",
"x-categories": ""
}
}
}
}


### フォルダ名に日本語を使っている場合

通常、HTTP ヘッダーに日本語を含めると文字化け(Mojibake)が発生しますが、本サーバーは **CLINE から送られる日本語ヘッダーを自動的にデコードして復元する機能**を備えています。

そのため、多くの場合で特段の配慮なく `x-roots` 等に日本語を記載できます。

&gt; [!TIP]
&gt; もしヘッダーでの指定で正しく動作しない場合は、**URL のクエリパラメータ**に記載することでより確実に設定可能です。

| 目的 | クエリパラメータ | 例 |
|------|----------------|-----|
| ルートフォルダ指定 | `roots=` | `?roots=グループA` |
| サブフォルダ指定 | `categories=` | `?categories=カテゴリA` |
| 複数指定 | カンマ区切り | `?categories=カテゴリA,カテゴリB` |
```json
{
  &quot;mcpServers&quot;: {
    &quot;local-rag&quot;: {
      &quot;url&quot;: &quot;http://localhost:8000/sse?categories=カテゴリA,カテゴリB&quot;,
      &quot;headers&quot;: {
        &quot;x-api-key&quot;: &quot;your-api-key-here&quot;
      }
    }
  }
}
パラメータ / ヘッダー 説明 日本語対応
x-api-key (ヘッダー) acl.json に定義した API キー ―
x-roots (ヘッダー) デフォルトで検索するルートフォルダ ✅(Mojibake自動修復)
roots (URL クエリ) 同上(URLパラメータなら確実) ✅
x-categories (ヘッダー) デフォルトで検索するサブフォルダ ✅(Mojibake自動修復)
categories (URL クエリ) 同上(URLパラメータなら確実) ✅

ドキュメントの追加方法

アクセス権を持つ共有フォルダ(ルートフォルダ)に、ファイルをコピーまたは保存するだけです。

> 反映タイミング: ファイルを追加しても検索に即時反映されません。次回の自動インデックス更新後(深夜バッチ等)に反映されます。すぐに反映させたい場合は CLINE のチャット欄に以下のように入力してください。

>&gt; ドキュメントのインデックスを今すぐ更新してください。 &gt;

> CLINE が自動的に update_index ツールを呼び出し、バックグラウンドで更新を開始します。進捗を確認したい場合は インデックスの更新状況を教えてください。 と入力してください。

アクセス権について

  • フォルダの読み書き権限は OS のファイル共有設定で管理します
  • MCP サーバーの API キーは「どのルートフォルダを検索できるか」を制御するものです
  • フォルダへの OS アクセス権があっても、API キー権限がなければ検索できません(逆も同様)

API キーを設定しなかった場合の動作

API キーを未設定のまま接続した場合の動作は、acl.json の _default 設定によって決まります。

acl.json の状態 動作
_default エントリが定義されている _default の allowed_roots に指定されたルートフォルダのみ検索可能
_default エントリが定義されていない 全アクセス拒否(「Access denied」エラーになる)

> 管理者が _default に &quot;Public&quot; などのフォルダを設定している場合は、API キーなしでも Public フォルダのみ検索できます。自分専用のフォルダにアクセスしたい場合は API キーの発行を管理者に依頼してください。

対応ファイル形式

形式 拡張子 備考
PDF .pdf テキスト抽出 + 画像ページは OCR
Word .docx テキスト抽出
Excel .xlsx 全シートのセル値を抽出
PowerPoint .pptx 全スライドのテキストを抽出
画像 .png .jpg .jpeg .bmp OCR でテキスト抽出
テキスト .txt .md + extra_text_extensions で指定したもの そのまま読み込み
設定ファイル等 .json .xml .yaml .yml .toml .ini .env .log .conf そのまま読み込み
Web .html .htm .css .js .ts そのまま読み込み
Python .py そのまま読み込み
C / C++ .c .cpp .cc .cxx .h .hpp .hxx そのまま読み込み
Verilog / SystemVerilog .v .sv .svh .vh そのまま読み込み
Rust .rs そのまま読み込み
Go .go そのまま読み込み
Java / Kotlin .java .kt そのまま読み込み
シェルスクリプト等 .sh .bash .bat .ps1 そのまま読み込み
その他言語 .rb .php .swift .cs そのまま読み込み

> 対応していない形式: .xls(旧 Excel)・.doc(旧 Word)・動画・音声ファイルなど。

制約事項

項目 制約内容
検索範囲 自分の API キーに紐づいたルートフォルダのみ検索可能
API キー未設定時 acl.json の _default 設定に従う
取得件数 1回の検索でデフォルト5件(n_results パラメータで変更可)
リアルタイム反映 ファイル追加後は次回インデックス更新まで検索に反映されない
OCR 精度 画像型 PDF や手書き文書は OCR モデルの精度に依存
日本語フォルダ名 検索は問題なし。CLINE の接続設定でのヘッダー指定は文字化けあり(URLクエリ使用推奨)

管理者に依頼が必要な事項

依頼内容 説明
API キーの発行 初回利用時や CLINE 接続設定に必要
共有フォルダのアクセス権変更 別のルートフォルダへの読み書き権限を追加したい場合
MCP 検索権限の変更 API キーの allowed_roots を変更したい場合
インデックスの即時更新・強制再構築 すぐに検索反映させたい場合や検索結果がおかしい場合
新しいファイル形式への対応 未対応形式を追加したい場合(要開発対応)

よくある質問

Q. 検索しても関連するドキュメントが出てこない
A. 以下を確認してください。
- 共有フォルダにファイルが追加されているか確認する
- 追加後にインデックス更新が完了しているか確認する(深夜バッチ or 手動更新)
- 検索クエリを別の言い回しで試してみる(日本語・英語どちらも可)

Q. 特定のフォルダの文書は見えるがほかのフォルダが見えない
A. API キーの権限(allowed_roots)に対象ルートフォルダが含まれていない可能性があります。管理者にアクセス権の追加を依頼してください。

Q. インデックスを今すぐ更新したい
A. CLINE のチャット欄に以下のように入力するだけで更新が始まります。難しい操作は不要です。

> 更新の開始
>&gt; ドキュメントのインデックスを今すぐ更新してください。 &gt;
>
> 進捗の確認
>&gt; インデックスの更新状況を教えてください。 &gt;
>
> CLINE が update_index / get_sync_status ツールをそれぞれ呼び出します。数十ファイルであれば数分で完了します。

Q. PDF の内容が正しく検索されない
A. 画像として作成された PDF(スキャンした文書など)は OCR 処理されますが、画質や言語によっては精度が下がる場合があります。管理者にご相談ください。

Q. CLINE にサーバーの URL や API キーをどう設定すればいいか
A. 管理者から提供された URL・API キーを CLINE の MCP サーバー設定に入力してください。設定方法は「CLINE への接続設定」を参照してください。



📖 リファレンス

利用できるツール (MCP Tools)

ツール名 説明
search_documents 自然言語クエリでドキュメントを検索(結果は自動的にコンテキスト制限が適用)
list_roots アクセス可能なルートフォルダ一覧
list_categories アクセス可能なカテゴリ(サブフォルダ)一覧
get_document_content 指定パスのドキュメント取得(巨大ドキュメントは自動圧縮、section で特定セクション詳細取得可)
list_documents インデックス済みドキュメント一覧
update_index インデックスをバックグラウンドで更新
get_sync_status インデックス更新の進捗確認

search_documents パラメータ

パラメータ 型 説明
query string 検索クエリ(必須)
root string 絞り込むルートフォルダ名(省略可)
category string 絞り込むカテゴリ名(省略可)
n_results integer 取得件数(デフォルト: 5)

get_document_content パラメータ

パラメータ 型 説明
path string ドキュメントの相対パス(必須)
section string 取得するセクションの見出し名(省略可。指定すると該当セクションのみ全文取得)

> セクション指定の例: get_document_content(path=&quot;manual.md&quot;, section=&quot;1. インストール手順&quot;)
>
> 巨大ドキュメントで特定の章だけ詳しく読みたい場合に使用します。セクション名が見つからない場合は、利用可能なセクション一覧が返されます。

ファイル構成```

local-rag-mcp-servr/
├── server.py # MCP サーバー本体(SSE / stdio)
├── rag_engine.py # RAG エンジン(ChromaDB / Ollama)
├── context_budget.py # コンテキスト予算管理(巨大ドキュメント圧縮・トークン制限)
├── file_converter.py # 文書変換エンジン(PDF OCR 等)
├── file_watcher.py # ファイル変更監視(watchdog)
├── update_index.py # インデックス手動更新ツール
├── _generate_source_hashes.py # 既存環境向けハッシュ生成ツール(OCRスキップ用)
├── stop.py # サーバー停止ツール
├── _cleanup_db.py # DB メンテナンスツール(バックスラッシュパス削除)
├── config.json # 設定ファイル
├── acl.json # アクセス制御設定
├── requirements.txt # Python 依存パッケージ
├── CHANGELOG.md # 更新履歴
└── README.md # このファイル


---

## ライセンス

MIT License

### サードパーティライセンス

本プロジェクトは OCR 処理のオプションとして **PaddleOCR** をサポートしています。
PaddleOCR は Apache License 2.0 の下でライセンスされています。```text
Apache License
Version 2.0, January 2004
http://www.apache.org/licenses/

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Local Rag MCP Server 怎么安装?

在客户端按下面的安装命令接入:python -m venv venv。装完在客户端配置里引用同一个包或端点。

Local Rag MCP Server 怎么在 Cline 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Local Rag MCP Server 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Local Rag MCP Server 需要 API Key 吗?

资料标注需要API Key认证,使用前准备好对应凭据,并按最小权限配置。

Local Rag MCP Server 支持哪些客户端?

资料标注支持 Cline;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Local Rag MCP Server 能提供哪些能力?

资料显示约 7 个工具;能力标签包括 文档处理、搜索、Python、Cline、文档转换。具体工具清单以官方文档为准。

Local Rag MCP Server 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Local Rag MCP Server 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。