local-rag-mcp

MCP搜索检索

提供方 heggria

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

A local code RAG MCP server that combines hybrid retrieval, vector search, and reranking to provide high-availability codebase Q&A, debugging, and feature development support for LLMs.

一句话选型结论

按资料字段整理

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

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

工具与能力

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

能力标签

Local Deployment Code Search Retrieval-Augmented Generation TypeScript MCP Server Hybrid Search Vector Search Codebase Q&A Developer Productivity

支持客户端

适用场景

Local DeploymentCode SearchRetrieval-Augmented Generation

安装与配置

stdio · 本地进程 API Key
客户端在本机拉起子进程,数据不出本机
node /绝对路径/to/rag-mcp/dist/index.js

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

  1. 1
    准备运行环境

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

  2. 2
    安装服务

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

  3. 3
    写入客户端配置

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

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

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

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

资料聚合

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

情报与竞品检索

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

选择建议

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

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude Desktop、Claude、Cursor,换客户端不用重新研究配置。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好API Key对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

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

不太适合

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

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
local-rag-mcp当前 未标注 stdio · 本地进程 本地部署 有 2026-01-23
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

服务器档案

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

详细介绍

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

Local Code RAG MCP Server

一个高可用、零依赖的本地代码检索增强生成(RAG)MCP 服务器。专为配合大语言模型(LLM)进行代码库问答、调试和功能开发而设计。

✨ 核心特性

本项目致力于解决本地代码检索中的痛点,提供企业级的稳定性和检索精度:

  • 🚀 高可用性 (High Resilience)
  • 自动降级策略:启动时自动检测环境。如果高性能组件(如 LanceDB)初始化失败,自动无缝切换到纯内存模式(Memory Mode),保证 99.9% 的启动成功率。
  • 多级 Worker 池:Embedding 服务采用 Worker Pool 并行处理,若失败则自动降级为单 Worker 甚至主线程模式。

  • 🎯 混合检索 (Hybrid Search)

  • 精度 >85%:结合了语义向量检索 (Vector Search) 和 关键词匹配 (Keyword Matching)。
  • 智能重排序 (Reranking):先通过向量检索召回 3 倍候选集,再利用关键词覆盖率进行加权重排序(70% 语义 + 30% 关键词),有效解决了纯向量检索无法精准定位函数名、变量名的问题。

  • ⚡ 极致性能

  • 并行索引:支持多流并发读取文件和 Batch 批量 Embedding 生成,速度提升 3-5 倍。
  • 智能缓存:内置去重和 Embedding 缓存机制,增量索引极其迅速。
  • 低延迟:千级文件项目查询延迟 < 200ms。

  • 🔒 隐私与离线

  • 完全本地化:所有模型(Embeddings)和向量库均在本地运行,无需任何外网 API 调用,确保代码隐私安全。

🏗 技术架构

本项目采用了分层架构设计,确保了模块的解耦和扩展性。```mermaid
graph TD
Client[MCP Client (Claude/Cursor)] --> Transport[Stdio Transport]
Transport --> Server[MCP Server]

subgraph Core Logic
    Server --&gt; SearchHandler[Code Search Handler]
    Server --&gt; FileIndexer[File Indexer]

    SearchHandler --&gt; HybridRanker[Hybrid Reranker]
    SearchHandler --&gt; VectorStore[Vector Store Adapter]

    FileIndexer --&gt; Chunker[Chunker Adapter]
    FileIndexer --&gt; EmbeddingSvc[Embedding Service]
    FileIndexer --&gt; VectorStore

    EmbeddingSvc --&gt; WorkerPool[Worker Pool]
    WorkerPool -- Parallel --&gt; Model[Local ONNX Model]
end

subgraph Storage Layer
    VectorStore -- Primary --&gt; LanceDB[(LanceDB Filesystem)]
    VectorStore -- Fallback --&gt; MemoryDB[(In-Memory Map)]
end

### 关键模块说明

1.  **VectorStoreAdapter (存储适配器)**
    - 实现策略模式,自动选择最佳存储引擎。
    - **Primary**: `LanceDB` (C++ Native),高性能持久化存储。
    - **Fallback**: `MemoryVectorStore` (纯 JS),无本机依赖,兼容性极强。

2.  **EmbeddingService (向量化服务)**
    - 管理本地量化模型 (Quantized ONNX models)。
    - 实现 Worker 线程池,避免阻塞 Node.js 主线程。
- 支持 `auto` · `bge-small` · `all-minilm` 多种模型选择。

3.  **CodeSearchHandler (检索处理器)**
    - **Context Injection**: 在 Chunk 中注入文件路径、AST 上下文(类名/函数名),提升语义理解。
    - 执行“向量召回 -&gt; 关键词提取 -&gt; 混合打分”的流水线。

## 📦 安装与使用

### 环境要求

- Node.js &gt;= 18.0.0
- (可选) Python 环境(如果涉及特定构建脚本)

### 快速开始

1.  **安装依赖**```bash
    npm install
    # 可选:安装高性能向量库(推荐)
    npm install @lancedb/lancedb
    ```

2.  **构建项目**```bash
    npm run build
    ```

3.  **下载模型 (首次运行自动,或手动预下载)**```bash
    # 脚本会自动下载所需的 ONNX 模型到 resources/models
    npm run download-grammars
    ```

4.  **配置 MCP (以 Claude Desktop 为例)**
    在 `~/Library/Application Support/Claude/claude_desktop_config.json` 中添加:```json
    {
      &quot;mcpServers&quot;: {
        &quot;local-code-rag&quot;: {
          &quot;command&quot;: &quot;node&quot;,
          &quot;args&quot;: [&quot;/绝对路径/to/rag-mcp/dist/index.js&quot;],
          &quot;env&quot;: {
            &quot;EMBEDDING_WORKERS&quot;: &quot;4&quot;
          }
        }
      }
    }
    ```

## 🛠 配置选项

你可以通过环境变量来调整服务器行为:

| 环境变量             | 默认值  | 说明                                         |
| -------------------- | ------- | -------------------------------------------- |
| `EMBEDDING_WORKERS`  | `4`     | 向量化工作的并行 Worker 数量                 |
| `EMBEDDING_WORKERS_MAX` | (auto) | 自动分配模式下的 Worker 上限(防止过度并行) |
| `EMBEDDING_WORKER_MEM_GB` | `3` | 自动分配模式下每个 Worker 预估占用内存(GB),用于按内存上限缩 worker |
| `EMBEDDING_BATCH_SIZE` | `512`  | 索引时单次送入 `embedBatch` 的外层批次大小(过大可能导致卡顿/超时) |
| `EMBEDDING_MAX_SUB_BATCH_SIZE` | `128` | `embedBatch` 内部子批次上限,用于避免超大 batch 造成 worker 卡死 |
| `EMBEDDING_MAX_SUB_BATCH_CHARS` | `160000` | `embedBatch` 内部子批次字符上限(防止少量超大 chunk 撑爆内存) |
| `EMBEDDING_TIMEOUT_PER_TEXT_MS` | `400` | 批量向量化超时系数(每条文本 ms),机器慢可调大 |
| `EMBEDDING_TIMEOUT_PER_CHAR_MS` | `0.1` | 批量向量化按字符估算超时系数(ms/char),用于超大文本场景 |
| `EMBEDDING_BATCH_TIMEOUT_MIN_MS` | `10000` | 批量向量化超时下限 |
| `EMBEDDING_BATCH_TIMEOUT_MAX_MS` | `300000` | 批量向量化超时上限 |
| `EMBEDDING_BATCH_TIMEOUT_SAFETY` | `3` | 批量向量化超时安全系数(估算值 × safety) |
| `EMBEDDING_BATCH_RETRIES` | `1` | 子批次超时/错误后的自动重试次数(会自动二分子批次) |
| `EMBEDDING_PROVIDER` | `local` | Embedding 后端:`local`(内置 worker/CPU) / `ollama`(HTTP 调 Ollama,GPU 跑大模型) |
| `OLLAMA_HOST` | `http://127.0.0.1:11434` | Ollama 服务地址(本机默认) |
| `OLLAMA_EMBED_MODEL` | `nomic-embed-text` | Ollama Embedding 模型名(也兼容读 `OLLAMA_MODEL`) |
| `OLLAMA_BATCH_ENDPOINT` | `auto` | 批量接口:`auto`(优先 `/api/embed`,不支持则退回 `/api/embeddings`) / `embed` / `embeddings` |
| `OLLAMA_CONCURRENCY` | `1` | Ollama 批量请求并发上限(GPU/显存紧张建议保持 1) |
| `OLLAMA_TIMEOUT_MULTIPLIER` | `2` | Ollama 请求超时倍率(把内部估算 timeout 乘以该值,避免 GPU 排队导致误超时) |
| `OLLAMA_REQUEST_TIMEOUT_MS` | (unset) | Ollama 请求超时硬下限(ms),最终 timeout = max(估算×倍率, 该值) |
| `OLLAMA_BATCH_RETRIES` | `3` | Ollama 子批次超时/错误后的最大重试次数(会持续二分子批次直到成功或到达上限) |
| `VECTOR_DIM` | `384` | LanceDB 向量维度初始值(一般无需设置;启动会按 Embedding 实际维度自动校验/重建) |
| `VECTORSTORE_RESET_ON_DIM_MISMATCH` | `false` | Embedding 维度与现有 LanceDB 表不一致时自动重建表(会清空旧向量) |
| `RAG_CACHE_DIR` / `VECTORSTORE_PATH` | (unset) | 覆盖默认缓存/向量库目录(默认 `/.rag-cache`),便于按不同模型隔离索引或做基准测试 |
| `MAX_FILES`          | `50000` | 最大索引文件数量限制                         |
| `FILE_BATCH_SIZE`    | `150`   | 单次处理的文件批次大小                       |
| `EMBEDDING_MODEL`    | `auto`  | 指定模型 (`auto`, `bge-small`, `all-minilm`) |
| `ENABLE_DEDUP_CACHE` | `true`  | 是否启用 Embedding 去重缓存                  |
| `SEARCH_TOP_K` | `10` | 默认返回给 LLM 的片段数量(推荐设为 `3`-`5`) |
| `RETRIEVAL_CANDIDATES` | `50` | 向量召回候选数(推荐 `50`),用于后续 rerank |
| `RERANK_PROVIDER` | `none` | 重排序提供方:`none` / `transformers` / `jina` / `mixedbread` |
| `RERANK_CANDIDATES` | `50` | 送入 rerank 的候选数量(默认等于 `RETRIEVAL_CANDIDATES`,受召回数量影响) |
| `RERANK_MODEL` | (provider default) | 重排序模型名(对 `transformers`/`jina` 生效;Mixedbread 用 `MIXEDBREAD_RERANK_MODEL`) |
| `RERANK_MODEL_PATH` | `./resources/models` | 本地 transformers 重排序模型目录(等价 `TRANSFORMERS_RERANK_MODEL_PATH`) |
| `RERANK_BASE_URL` | (unset) | HTTP 重排序服务 base URL(对 `jina`/`mixedbread` 生效;也可用各自专用变量) |
| `RERANK_API_KEY` | (unset) | HTTP 重排序服务 API Key(也可用 `JINA_API_KEY`/`MIXEDBREAD_API_KEY`) |
| `RERANK_OFFLINE` | `true` | 本地 transformers 重排序是否禁用远程下载(推荐保持 `true`) |
| `RERANK_WASM_THREADS` | (auto) | 本地 transformers 重排序 WASM 线程数(上限 8) |
| `RERANK_MAX_DOC_CHARS` | `2000` | 单个候选最大字符数(控制上下文与性能) |
| `MIXEDBREAD_API_KEY` | (unset) | Mixedbread API Key(启用 `RERANK_PROVIDER=mixedbread` 必填) |
| `MIXEDBREAD_RERANK_MODEL` | `mxbai-rerank-large-v2` | Mixedbread 重排序模型名 |
| `MIXEDBREAD_BASE_URL` | `https://api.mixedbread.ai` | Mixedbread API Base URL |
| `MIXEDBREAD_TIMEOUT_MS` | `15000` | Mixedbread 请求超时(ms) |
| `MIXEDBREAD_MAX_DOC_CHARS` | `2000` | 单个候选文本最大字符数(用于控制请求体大小) |
| `JINA_RERANK_BASE_URL` | `http://127.0.0.1:8000` | Jina Rerank API Base URL(本地部署推荐) |
| `JINA_API_KEY` | (unset) | Jina API Key(本地部署可不填;云 API 需要) |
| `JINA_RERANK_MODEL` | `jina-reranker-v3` | Jina 重排序模型名 |
| `JINA_RERANK_TIMEOUT_MS` | `15000` | Jina 重排序请求超时(ms) |
| `JINA_RERANK_MAX_DOC_CHARS` | `2000` | 单个候选文本最大字符数(用于控制请求体大小) |
| `TRANSFORMERS_RERANK_MODEL` | `Xenova/bge-reranker-base` | 本地 transformers 重排序模型(推荐) |
| `TRANSFORMERS_RERANK_MODEL_PATH` | `./resources/models` | transformers.js `env.localModelPath` |
| `TRANSFORMERS_RERANK_OFFLINE` | `true` | 同 `RERANK_OFFLINE`(别名) |
| `TRANSFORMERS_RERANK_WASM_THREADS` | (auto) | 同 `RERANK_WASM_THREADS`(别名) |
| `TRANSFORMERS_RERANK_MAX_DOC_CHARS` | `2000` | 同 `RERANK_MAX_DOC_CHARS`(别名) |

### 本地 Jina Reranker v3(/v1/rerank)

本项目的 `RERANK_PROVIDER=jina` 通过 HTTP 调用 `POST /v1/rerank`(可对接你自己在本机/内网部署的服务),因此可以做到“权重本地、请求不出网”(首次下载模型权重除外)。

最小配置示例(假设你的本地服务跑在 `http://127.0.0.1:8000`):```bash
export RERANK_PROVIDER=jina
export JINA_RERANK_BASE_URL=http://127.0.0.1:8000
export JINA_RERANK_MODEL=jina-reranker-v3

本地 Transformers Reranker(Xenova/bge-reranker-base)

启用方式:```bash
export SEARCH_TOP_K=5
export RETRIEVAL_CANDIDATES=50
export RERANK_PROVIDER=transformers
export RERANK_MODEL=Xenova/bge-reranker-base
export RERANK_MODEL_PATH=./resources/models
export RERANK_OFFLINE=true


注意:当 `RERANK_OFFLINE=true` 时,模型必须已存在于 `RERANK_MODEL_PATH`(也可用 `TRANSFORMERS_RERANK_MODEL_PATH`)。

### Ollama Embedding (GPU 模式)

如果你希望用 GPU 跑更大的 Embedding 模型(Node 进程只做索引/搜索逻辑),确保本机已启动 Ollama 服务,然后设置:```bash
export EMBEDDING_PROVIDER=ollama
export OLLAMA_EMBED_MODEL=nomic-embed-text   # 或你本地已有的 embedding 模型
# 可选:export OLLAMA_HOST=http://127.0.0.1:11434

# 如果从 384 维模型切换到 1024 维(如 BGE-M3),请先清理旧库或启用自动重建:
# npm run clean
# 或:export VECTORSTORE_RESET_ON_DIM_MISMATCH=1

📂 项目结构```

src/
├── embeddings/ # Embedding 生成服务与 Worker 线程管理
├── handlers/ # MCP 请求处理器 (Search Logic)
├── indexing/ # 文件扫描、分块 (Chunking)、AST 解析
├── storage/ # 向量数据库适配器 (LanceDB/Memory)
├── utils/ # 通用工具 (Logger, Performance Monitor)
└── index.ts # 程序入口与 MCP Server 定义
```

📊 性能基准

在 M1 Macbook Pro 上对 1000 个 TypeScript 文件的测试数据:

  • 索引速度: ~50 files/sec
  • 查询延迟: < 150ms (P95)
  • 内存占用: ~300MB (Memory Mode) / ~150MB (LanceDB Mode)

🤝 贡献

欢迎提交 Pull Request 或 Issue!

  1. Fork 本仓库
  2. 创建特性分支 (git checkout -b feature/AmazingFeature)
  3. 提交更改 (git commit -m &#x27;Add some AmazingFeature&#x27;)
  4. 推送到分支 (git push origin feature/AmazingFeature)
  5. 开启 Pull Request

📄 许可证

MIT License

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
local-rag-mcp 怎么安装?

在客户端按下面的安装命令接入:node /绝对路径/to/rag-mcp/dist/index.js。装完在客户端配置里引用同一个包或端点。

local-rag-mcp 怎么在 Claude Desktop、Claude、Cursor 里配置?

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

local-rag-mcp 收费吗?

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

local-rag-mcp 需要 API Key 吗?

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

local-rag-mcp 支持哪些客户端?

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

local-rag-mcp 能提供哪些能力?

资料显示能力标签包括 Local Deployment、Code Search、Retrieval-Augmented Generation、TypeScript、MCP Server、Hybrid Search。具体工具清单以官方文档为准。

local-rag-mcp 需要什么运行环境?

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

local-rag-mcp 是本地还是远程?

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

热门专题

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

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