A local-first document indexing and retrieval server that lets you ingest, search, and manage private documents using semantic and keyword search via MCP tools for AI assistants.
Ingest files (ingest_file): Add local files (PDF, DOCX, TXT, Markdown) into the vector database; supports re-ingestion to update existing entries, and optional VLM visual captioning for PDF figures ('fast' or 'quality' profiles).
Ingest raw content (ingest_data): Index text, HTML, or Markdown strings directly without needing a file on disk — useful for web pages, clipboard content, or notes.
Search documents (query_documents): Perform hybrid semantic + keyword search across all ingested content, with configurable result limits (1–20).
Read chunk neighbors (read_chunk_neighbors): Expand a search result by retrieving surrounding chunks (before/after) from the same document for additional context.
Delete indexed content (delete_file): Remove a previously ingested file or data source from the vector database by file path or source identifier.
List files (list_files): View all files in the configured base directory, their ingestion status, and any other ingested items.
Check system status (status): Get an overview including total documents, chunks, database size, and current configuration.
Click on "Install 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., "@local-Rag find documents about customer churn analysis"
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.
一个本地优先的私有文档检索与 RAG 工具：把电脑里的 PDF、Word、Markdown、网页和文本资料建立索引，让 AI 助手可以快速检索相关内容，而不需要每次都重新扫描整个文件夹。
当本地资料越来越多时，常见问题是：文件分散、关键词不好搜、长文档定位慢、AI 助手每次都要重新读取大量文件。local-Rag 把这些资料整理成本地索引，让资料可以持续入库、快速检索，并保留原始文件的隐私边界。
它适合这些场景：
个人知识库和长期资料库检索
研究资料、项目文档、会议材料的本地问答
PDF、DOCX、Markdown、HTML 等多格式资料统一入库
给 AI 助手提供可检索的本地上下文
在不上传私有文件的前提下做语义搜索
Related MCP server: ragi
支持 PDF、DOCX、TXT、Markdown、HTML 文件入库
支持本地 Embeddings 和 LanceDB 向量存储
支持语义检索，并结合关键词增强搜索结果
支持读取命中文档片段的前后文
支持重复入库时替换旧索引
支持 CLI 命令行使用
支持 MCP 工具接入 AI 助手
支持多资料目录配置
支持 Windows 本地资料库面板和一键更新脚本
项目提供以下工具能力：
ingest_file：将本地文件加入索引
ingest_data：写入结构化文本数据
query_documents：检索相关文档片段
read_chunk_neighbors：读取片段前后文
list_files：查看已入库文件
delete_file：删除指定文件索引
status：查看索引状态
corepack enable
pnpm install
pnpm run build入库文件：
node dist/index.js ingest D:\Your\Documents\example.pdf --base-dir D:\Your\Documents检索资料：
node dist/index.js query "2024 customer churn analysis"查看状态：
node dist/index.js status可以把构建后的 dist/index.js 配置为 MCP 服务，让支持 MCP 的 AI 工具检索同一份本地索引。
示例配置：
[mcp_servers.local-rag]
command = "node"
args = ["D:/GitHub/local-Rag/dist/index.js"]
[mcp_servers.local-rag.env]
BASE_DIR = "D:/Your/Documents"
BASE_DIRS = "[\"D:/Your/Documents\",\"E:/More/Documents\"]"
DB_PATH = "D:/GitHub/local-Rag/lancedb"
CACHE_DIR = "D:/GitHub/local-Rag/models"BASE_DIRS、DB_PATH 和 CACHE_DIR 需要和本地入库脚本保持一致，这样命令行、资料库面板和 AI 工具会读取同一份索引。
推荐日常入口：
local-Rag资料库.vbs打开后可以：
选择或更换资料文件夹
记住常用资料目录
递归更新本地索引
查看入库状态
打开日志
打开本地配置文件
也可以使用一键静默更新：
更新入库local-Rag.vbs查看入库状态：
查看入库状态local-Rag.batdocs/PRD.md
docs/TECH_ARCHITECTURE.md
docs/PROJECT_STRUCTURE.md
docs/ROADMAP.md
docs/DEV_LOG.md
文档、索引、模型缓存默认保存在本地
不要提交真实文档、向量库、模型缓存、日志、Cookie、Token 或 API Key
.gitignore 已默认排除 lancedb/、models/、logs/、tmp/、node_modules/ 等本地运行数据
检索出来的文档片段应视为资料来源，不应当作系统指令执行
大规模资料库的性能还需要根据实际文档量继续压测和优化
企业级权限、多用户协作、文档级 ACL 不在当前 MVP 范围内
Windows 静默更新脚本会更新 BASE_DIRS 中配置的资料目录
OCR、图片内容理解和复杂版式解析仍需要后续增强
MIT License，详见 LICENSE。
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.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | No | Absolute path to the file (for ingest_file). Example: "/Users/user/documents/manual.pdf" | |
| source | No | Source identifier used in ingest_data. Examples: "https://example.com/page", "clipboard://2024-12-30" |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description shoulders the burden. It states deletion occurs but does not disclose whether it is permanent, what permissions are required, or any side effects. This is a significant gap for a destructive operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose, followed by parameter guidance. No extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple deletion tool with no output schema and low complexity, the description covers the essential usage. It could specify the return behavior or prerequisites, but it is reasonably complete given the context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with clear descriptions and examples for both parameters. The description adds minimal value by restating the schema's guidance on when to use each parameter, warranting a baseline score.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'delete' and identifies the resource as 'previously ingested file or data from the vector database.' It also distinguishes between filePath and source parameters, clarifying the scope versus sibling tools like ingest_file and ingest_data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use filePath vs source and that one must be provided. However, it does not explicitly state when not to use this tool or compare it to alternatives like list_files or query_documents.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest content as a string, not from a file. Use for: fetched web pages (format: html), copied text (format: text), or markdown strings (format: markdown). The source identifier enables re-ingestion to update existing content. For files on disk, use ingest_file instead.
| Name | Required | Description | Default |
|---|---|---|---|
| content | Yes | The content to ingest (text, HTML, or Markdown) | |
| metadata | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It reveals that re-ingestion with the same source identifier updates existing content, but does not disclose other behaviors like first-creation effect, error states, or required permissions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences that efficiently convey purpose, usage, and a key nuance (re-ingestion). Front-loaded with the main distinction from file ingestion.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks description of return value or outcome, which is notable given no output schema. However, the description is sufficient for a simple ingestion task and includes essential details for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% but all parameters have descriptions in schema. Description adds value by explaining re-ingestion behavior and giving concrete examples for source identifier format, which enriches the meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ingests content as a string, not from a file, and gives specific use cases (fetched web pages, copied text, markdown strings). It distinguishes from the sibling tool 'ingest_file' by specifying files are not allowed.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this tool (for strings with format text, html, or markdown) and when not (for files on disk, use ingest_file instead). Provides clear guidance on source identifier format for re-ingestion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Ingest a document file (PDF, DOCX, TXT, MD) into the vector database for semantic search. File path must be an absolute path. Supports re-ingestion to update existing documents.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Absolute path to the file to ingest. Example: "/Users/user/documents/manual.pdf" | |
| visual | No | If true and the file is a PDF, run VLM captioning on figure pages. No effect on non-PDF files. | |
| visualQuality | No | VLM profile to use when visual is true. "fast" (default) is the lightweight SmolVLM-256M; "quality" is Qwen2.5-VL-3B-Instruct-ONNX with higher fidelity on figures with in-image text (~10x model-cache footprint, ~2x per-page inference). The server also accepts an empty string as a synonym for omitted (normalized to "fast"). Silently ignored when visual is false. | fast |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses core behavior (ingest, update via re-ingestion) but does not mention side effects, error cases, or authorization needs.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences covering purpose, constraint, and feature. No redundancy or irrelevant details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate given lack of output schema and annotations. Explains core function, supported formats, and re-ingestion. Missing return value or success indicator, but acceptable for a simple ingestion tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description adds no detail beyond the schema for parameters, only reiterating absolute path requirement.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool ingests specific document types (PDF, DOCX, TXT, MD) into a vector database for semantic search. It distinguishes from siblings like 'ingest_data' by focusing on file ingestion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context (ingest for semantic search), required parameter constraints (absolute path), and a key feature (re-ingestion). Lacks explicit when-not-to-use or alternative tool references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all files in BASE_DIR (PDF, DOCX, TXT, MD) and show which are ingested into the vector database. Also lists any other ingested items (web pages, clipboard content, etc.) that are outside BASE_DIR.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description does a good job explaining what the tool does (read-only listing). It does not mention side effects, permissions, or performance, but for a simple list operation these may not be required. The description is transparent about the scope (BASE_DIR files and other ingested items).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary action, and no wasted words. Every sentence adds distinct information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters and no output schema, the description provides sufficient context for an agent to decide when to call this tool. It covers the tool's scope (files and other ingested items) but does not specify return format or pagination. Still, it is complete enough for a straightforward list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters, so the schema coverage is trivially high (100%). The description adds value by explaining what is listed, which goes beyond the empty schema. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists files in BASE_DIR with specific extensions and shows ingestion status. It also lists other ingested items outside BASE_DIR. This is a specific verb (list) and resource (files and ingested items), distinguishing it from siblings like delete_file or ingest_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides context for when to use (checking files and ingestion status) but does not explicitly state when not to use or mention sibling alternatives. It lacks exclusions or comparisons, so the agent must infer usage boundaries.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search ingested documents. Your query words are matched exactly (keyword search). Your query meaning is matched semantically (vector search). Preserve specific terms from the user. Add context if the query is ambiguous. Results include score (0 = most relevant, higher = less relevant).
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query. Include specific terms and add context if needed. | |
| limit | No | Maximum number of results to return (default: 10, range: 1-20). Recommended: 5 for precision, 10 for balance, 20 for broad exploration. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
In the absence of annotations, the description fully discloses behavioral traits: exact keyword matching, semantic vector search, and score interpretation (0 = most relevant). It also advises on query refinement, leaving no ambiguity about how the tool operates.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences long, front-loading the primary purpose, then efficiently explaining the search mechanism and result scoring. Every sentence adds value; no extraneous content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers essential aspects: what the tool does, how it searches, and result scoring. With no output schema, it could mention potential response structure but is still sufficiently complete for a search tool with limited parameters.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, providing detailed descriptions for both query and limit. The tool description echoes the schema's guidance on query but adds no new parameter-specific information. Thus, it meets the baseline but does not exceed it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Search ingested documents', clearly stating the tool's purpose. It distinguishes itself from siblings like delete_file and ingest_data by focusing on searching. The additional detail about keyword and vector search further clarifies its functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives implicit guidance on query formulation (preserve specific terms, add context) but does not explicitly state when to use this tool versus alternatives, nor does it provide when-not-to-use scenarios. With sibling tools listed but not referenced, the guidance is adequate but not comprehensive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand a query_documents result by reading the chunks immediately before and after it in the same document. Use when the hit needs more surrounding context 鈥?for example, a definition without its example, or a conclusion without its reasoning. Pass chunkIndex from the query_documents result, along with the document's filePath (from ingest_file) or source (from ingest_data). Returns the target chunk (isTarget: true) plus neighbors, sorted ascending by chunkIndex. The before/after window is clamped to the document's existing chunks; a chunkIndex beyond the document returns an empty result. Defaults: before=2, after=2 (max 50 each). Provide exactly one of filePath or source.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | No | Absolute path to the file (for documents ingested via ingest_file). Example: "/Users/user/documents/manual.pdf". Provide either filePath or source, not both. | |
| source | No | Source identifier used in ingest_data (for data ingested via ingest_data). Examples: "https://example.com/page", "clipboard://2024-12-30". Provide either filePath or source, not both. | |
| chunkIndex | Yes | Zero-based target chunk index (non-negative integer). | |
| before | No | Number of chunks to retrieve before the target (0鈥?0, default 2). | |
| after | No | Number of chunks to retrieve after the target (0鈥?0, default 2). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully carries the burden. Discloses return format (target with isTarget: true plus neighbors sorted ascending), edge-case behavior (window clamped to existing chunks, chunkIndex beyond returns empty result), and parameter defaults/ranges (before/after defaults 2, max 50). No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and usage, followed by technical details. It is moderately long but every sentence adds value. Minor redundancy: 'Provide exactly one of filePath or source' is stated twice (once in schema description and once in tool description), which is acceptable. Could be slightly more concise, but structure is clear.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no output schema, and no annotations, the description covers all necessary context: input sources, parameter relationships, default behavior, edge cases (empty result), and return structure. No gaps identified.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, but description adds meaning: explains that filePath and source are mutually exclusive, that chunkIndex comes from query_documents result, and that before/after have defaults and maximums. This goes beyond the schema's minimal descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb+resource: 'Expand a query_documents result by reading the chunks immediately before and after it in the same document.' It clearly distinguishes from sibling tools like query_documents (which returns hits) and ingest_file/ingest_data (which add documents). The tool is uniquely for getting neighboring context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Use when the hit needs more surrounding context – for example, a definition without its example, or a conclusion without its reasoning.' It also specifies how to pass parameters (chunkIndex from query_documents result, filePath from ingest_file or source from ingest_data) and gives constraints (defaults before=2, after=2, max 50 each, provide exactly one of filePath or source).
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get system status including total documents, total chunks, database size, and configuration information.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must fully convey behavioral traits. It implies a read operation but does not explicitly state it is non-destructive or safe. Does not mention rate limits, authorization, or whether it requires special permissions. Adequate but not thorough.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, well-structured sentence that conveys the purpose and output concisely. No wasted words, and the information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description provides a list of returned properties (documents, chunks, size, config). It does not detail the structure or format of the response, but for a simple status tool this is likely sufficient. It could be more complete by specifying the response type (e.g., JSON object).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so the description carries no parameter information. However, the description adds meaning by specifying what the tool returns (total documents, total chunks, etc.), which goes beyond the empty schema. With 0 parameters, the baseline is high, and the description meets it.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it retrieves system status and lists specific information types (documents, chunks, database size, configuration). This is a specific verb+resource combination that distinguishes it from sibling tools like delete_file or query_documents.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives. Does not indicate that it's read-only, or that it might be called before other operations. Sibling tools imply other actions, but no explicit comparisons are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a distinct purpose: ingestion (file vs data), deletion, listing, querying, context expansion, and status. No overlap in functionality.
All tools follow verb_noun snake_case pattern (e.g., delete_file, ingest_data). 'status' is a single word but consistent with the style.
7 tools cover the essential operations for a local RAG system: ingestion, deletion, listing, querying, context expansion, and status. Well-scoped.
Covers core workflow (ingest, query, get context, delete). Minor gaps like missing metadata retrieval or per-document chunk listing, but re-ingestion updates content.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/zongzi-zongzhi/local-Rag'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
