Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-local-rag What do my documents say about handling PDF uploads?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
本地文档检索服务：在本机完成文档解析、向量化、LanceDB 存储和混合检索，不上传文档。 可通过 MCP 客户端或命令行使用。
要求：Node.js 22+。首次运行需要网络下载 npm 依赖和 embedding 模型；模型缓存后可离线运行。
pnpm install
pnpm build
$env:BASE_DIR = 'D:\Rag\documents'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容'默认索引为当前工作目录下的 lancedb。本项目 Windows 脚本统一使用 D:\Rag，目录结构为：
D:\Rag\documents
D:\Rag\models
D:\Rag\indexes\lancedb
D:\Rag\indexes\lancedb-intel-npu使用 npm CLI 时，建议显式设置绝对路径：
$env:BASE_DIR = 'D:\Rag\documents'
$env:DB_PATH = 'D:\Rag\indexes\lancedb'
npx mcp-local-rag sync
npx mcp-local-rag query '查询内容' --scope 'D:\Rag\documents\gmsl'也可以直接运行 npx -y mcp-local-rag 作为 MCP server，并在 MCP 客户端配置同样的
BASE_DIR、DB_PATH 等环境变量。
Related MCP server: ragi
文件：PDF、DOCX、Markdown、TXT。
HTML：由 MCP 客户端抓取后通过 ingest_data 传入。
检索：语义相似度与关键词匹配结合。
工具：sync_start、sync_status、ingest_file、ingest_data、query_documents、
read_chunk_neighbors、list_files、delete_file、status。
文件操作只能访问配置的文档根目录。修改模型、设备、精度或分块规则后，必须使用新的索引目录或重新建库。
全局安装后可直接使用以下命令：
npm install -g mcp-local-rag项目内安装时，在命令前加 npx，例如 npx mcp-local-rag-onnx sync。npm 包内部仍包含
tools/ 与 requirements-openvino.txt，无需手动定位它们。
以下脚本需要 Python 3.10+；标准 npm CLI 不需要 Python。默认文档根目录为
D:\Rag\documents，模型缓存为 D:\Rag\models。
与 NPU 脚本一样，通过子命令区分建库和查询。默认索引为
D:\Rag\indexes\lancedb：
mcp-local-rag-onnx sync
mcp-local-rag-onnx query '查询内容' `
--scope 'D:\Rag\documents\gmsl'sync 默认 webgpu，query 默认 cpu；两者均可通过 --device cpu|webgpu|dml
显式覆盖。例如使用 DirectML 建库：
mcp-local-rag-onnx sync --device dml。
建库批次默认是 8，可通过 sync --batch-size <数量> 调整；查询一次只嵌入一个问题，
批次固定为 1。
首次使用、删除 .openvino-venv 或更新 OpenVINO/NPU 驱动后执行一次。脚本会准备 FP32
模型并编译四个固定形状 [1,128]、[1,256]、[1,512]、[1,1024] 的 NPU blob：
mcp-local-rag-npu-setup在单独终端启动服务，并在建库或查询期间保持运行：
mcp-local-rag-npu-start健康检查只在排查问题时执行，不需要每次运行：
Invoke-RestMethod http://127.0.0.1:8765/health返回的 device 应为 NPU。服务不会自动回退 CPU，关闭服务进程或终端后服务才会停止。
在另一个终端建库或查询。默认 NPU 索引为 D:\Rag\indexes\lancedb-intel-npu：
mcp-local-rag-npu sync
mcp-local-rag-npu query '查询内容' `
--scope 'D:\Rag\documents\gmsl'可用 --database-path、--documents-root、--models-path 和 --endpoint 覆盖默认值。
NPU 服务按文本 token 数选择最小可容纳的固定长度，batch 固定为 1。
环境变量 | 默认值 | 作用 |
| 当前目录 | 文档根目录 |
|
| LanceDB 索引目录 |
|
| 模型缓存目录 |
|
| embedding 模型 |
|
| Transformers.js 设备，如 |
|
| embedding 精度 |
|
|
|
|
| OpenVINO 服务地址 |
RAG_EMBEDDER_BACKEND=openvino 时，必须先启动 OpenVINO 服务。不同模型或后端生成的向量
不可混用，应分别使用不同的 DB_PATH。
pnpm build
pnpm test
pnpm run check:all项目许可证为 MIT。
Delete a previously ingested file or data from the vector database. Use filePath for files ingested via ingest_file, or source for data ingested via ingest_data. Either filePath or source must be provided. Returns deleted (operation succeeded), removedChunks, and existed (whether anything was actually present).
Inputs: source, filePath.
Ingest in-memory content as a string (use ingest_file for files on disk). The source identifier enables re-ingestion to update existing content. Returns { filePath, chunkCount, timestamp, fileTitle }.
Inputs: content (required), metadata (required).
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database. Path must be absolute; re-ingesting the same path replaces its existing data. Returns { filePath, chunkCount, timestamp, fileTitle }.
Inputs: filePath (required), visual, visualQuality.
List supported files (PDF, DOCX, TXT, MD) under the configured base directories and whether each is ingested. Returns { baseDirs, files, sources }; sources lists ingested items reported apart from the file scan, chiefly ingest_data content (web pages, clipboard, etc.).
Inputs: scope.
Search ingested documents with hybrid keyword + semantic matching. Returns results sorted by relevance, each with filePath, chunkIndex, text, fileTitle, score (0 = best, higher = worse), and source (for ingest_data items).
Inputs: query (required), limit, scope.
Read the chunks immediately before and after a query_documents result, in the same document, for more surrounding context. Pass chunkIndex from the result plus exactly one of filePath (ingest_file) or source (ingest_data). Returns the target chunk (isTarget: true) and its neighbors, ascending by chunkIndex; an out-of-range chunkIndex returns []. Defaults: before=2, after=2 (max 50 each).
Inputs: chunkIndex (required), after, before, source, +1 more.
Get index status: { documentCount, chunkCount, memoryUsage (MB), uptime (s), ftsIndexEnabled, searchMode }.
Inputs: no named parameters.
Reconcile the index with the files on disk: ingest new and changed files, leave unchanged files alone, and remove index entries for files that are gone. Returns { jobId } without waiting for the run to finish; poll sync_status with that jobId for progress and the final outcome. Only one job is kept, and it is lost when the server process exits.
Inputs: path.
Get the current or latest sync job record: { jobId, state ("running" | "succeeded" | "failed"), total (null until scanning has counted the files on disk), completed (upserted + skipped + empty; pruned is counted separately), summary { upserted, skipped, empty, pruned }, warnings, error (null unless the job failed) }. An unknown jobId means the job was replaced by a newer one or lost with a previous server process.
Inputs: jobId (required).
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 9 tools
Each tool has a clear, non-overlapping purpose: status, query, two ingestion methods differentiated by source type, delete, list, context reading, and sync start/status. Even the two ingest tools are unambiguous due to explicit input-type distinction.
Most tools follow a verb_noun snake_case pattern (query_documents, ingest_file, delete_file, list_files, read_chunk_neighbors, sync_start, sync_status). The lone 'status' tool deviates slightly by being a bare noun rather than a verb action, but the overall naming is predictable and consistent.
With 9 tools, the server is well-scoped for a local RAG system. Each tool serves a distinct and necessary function: ingestion (file and data), querying, context exploration, deletion, listing, status, and synchronization, with no unnecessary bloat.
The tool set covers the full lifecycle: ingestion (create), querying (read), deletion (delete), and updating via re-ingestion or synchronization. Additional utilities like status, list_files, and read_chunk_neighbors fill out the surface for effective RAG management, leaving no obvious gaps.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
The Needle MCP server enables semantic search on documents stored in files like PDFs, DOCX, and XLSX by connecting AI applications to external data sources. It provides capabilities to create and manage document collections, perform natural language searches on stored content, and retrieve relevant information without requiring exact keyword matches.
