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