cherry-mcp

将 Cherry Studio 的本地知识库通过 MCP (Model Context Protocol) 暴露给 AI 客户端（Cursor、Claude Desktop、opencode 等）。

快速开始 · 参数配置 · 可用工具 · 本地开发

快速开始

在任何支持 MCP 的 AI 客户端配置文件中添加：

{
  "mcpServers": {
    "cherry-mcp": {
      "command": "npx",
      "args": [
        "-y", "cherry-mcp",
        "--embed-url", "http://127.0.0.1:1234",
        "--embed-model", "text-embedding-qwen3-embedding-8b",
        "--embed-dim", "4096"
      ]
    }
  }
}

[!TIP] --embed-api-key 使用本地模型时可省略；首次执行 npm 会自动安装依赖。

opencode 配置

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "cherry-mcp": {
      "type": "local",
      "command": [
        "npx", "-y", "cherry-mcp@latest",
        "--top-k", "10",
        "--threshold", "0.6",
        "--max-fetch", "1000",
        "--kb-path", "C:\\Users\\你的用户名\\AppData\\Roaming\\CherryStudio\\Data\\KnowledgeBase",
        "--embed-url", "http://127.0.0.1:1234",
        "--embed-model", "text-embedding-qwen3-embedding-8b",
        "--embed-dim", "4096"
      ],
      "enabled": true
    }
  }
}

更多配置示例请参阅 mcp-config.md

参数配置

所有参数支持 CLI 传入，也可通过环境变量注入。优先级：CLI 参数 > 环境变量

[!IMPORTANT] 以下参数为必填：--embed-url、--embed-model、--embed-dim

| CLI 参数 | 环境变量 | 默认值 | 说明 | |:---------|:---------|:-------|:-----| | --top-k <n> | DEFAULT_TOP_K | 20 | 最大返回结果数 | | --threshold <n> | DEFAULT_THRESHOLD | 0.5 | 最低相似度阈值（0-1） | | --max-fetch <n> | MAX_FETCH | 1000 | 每库最多读取的记录数 | | --kb-name <str> | DEFAULT_KB_NAME | - | 限定搜索指定名称的知识库 | | --kb-path <dir> | CHERRYSTUDIO_KB_PATH | 自动识别 | 知识库根目录路径（可覆盖默认值） | | --embed-url <url> | EMBEDDING_URL | (必填) | Embedding API 地址 | | --embed-api-key | EMBEDDING_API_KEY | - | API Token（本地模型可留空） | | --embed-model <id> | EMBEDDING_MODEL | (必填) | 向量模型 ID | | --embed-dim <n> | EMBEDDING_DIMENSION | (必填) | 向量维度（须与模型实际输出一致） |

完整参数说明请参阅 cli-params.md

可用工具

| 工具名 | 说明 | |:-------|:-----| | list_knowledge_bases | 列出所有知识库（名称、路径、向量数量、维度等） | | search_knowledge | 向量相似度检索，返回最相关的文档片段 |

本地开发

1. 克隆项目并安装依赖

git clone https://github.com/UserTheo02726/cherry-mcp.git
cd cherry-mcp
npm install

2. 配置调试参数

# 复制配置文件示例
cp dev/dev-config.json.example dev/dev-config.json

# 编辑配置文件，填入你的参数
vim dev/dev-config.json

配置文件说明：

{
  "embedUrl": "https://api.siliconflow.cn/v1/embeddings",
  "embedModel": "BAAI/bge-m3",
  "embedDim": 1024,
  "embedApiKey": "sk-xxx",
  "topK": 20,
  "threshold": 0.5,
  "maxFetch": 1000,
  "kbName": "",
  "kbPath": ""
}

3. 调试

方式 A：命令行调试

# 1. 列出所有工具
node dev/debug.js tools/list

# 2. 调用 list_knowledge_bases 工具
node dev/debug.js tools/call list_knowledge_bases

# 3. 调用 search_knowledge 工具
node dev/debug.js tools/call search_knowledge "<搜索关键词>" <返回结果数默认:5> <相似度阈值默认:0.6>

方式 B：使用 MCP Inspector

node dev/inspector.js

[!NOTE] MCP 服务启动后会等待 IDE 客户端连接，不会显示交互界面。

前置要求

• Node.js >= 22
• 已运行 Cherry Studio 并创建至少一个知识库
• 可访问的 Embedding API（本地 LM Studio 或远程 SiliconFlow 等）

TODO

• [ ] 优化 search_knowledge 工具的参数描述，减少 AI 主动传入 top_k、threshold、kb_name 等可选参数的行为
• [ ] list_knowledge_bases 返回的知识库名称是 Base62 ID，而非 GUI 中的自定义名称

常见问题

遇到问题请参阅 troubleshooting.md