# Cherry Studio Knowledge Base MCP Server

**一行配置，即刻使用。** 让 Claude、Cursor 等 AI 助手直接读取你的 Cherry Studio 知识库。

**One-line config, ready to use.** Let Claude, Cursor, and other AI assistants read your Cherry Studio knowledge bases directly.

## 客户端兼容性 / Client Compatibility

| 客户端 / Client | 状态 / Status | 备注 / Notes |
|:---:|:---:|:---|
| ✅ Codex | **已验证可用** | — |
| ✅ WorkBuddy | **已验证可用** | — |
| ⚠️ LobeHub | **可能无法使用** | 已知兼容性问题 / Known compatibility issues |

> 你的客户端不在这个列表？欢迎提交 Issue 反馈使用体验！  
> Your client not listed? Feel free to open an issue with your experience!

---

## 使用方法 / Usage

### 方式一：npx 直接运行（推荐，无需安装）/ Method 1: npx (Recommended, No Installation)

打开你的 AI 客户端配置（Claude Desktop / Cursor 等），粘贴以下 JSON：

Open your AI client config (Claude Desktop / Cursor, etc.), paste this JSON:

```json
{
  "mcpServers": {
    "cherrystudio-knowledgebase": {
      "command": "npx",
      "args": ["-y", "cherrystudio-knowledgebase-mcp"],
      "env": {
        "CHERRYSTUDIO_API_BASE_URL": "http://127.0.0.1:23333",
        "CHERRYSTUDIO_API_KEY": "cs-sk-your-api-key-here"
      }
    }
  }
}
```

**只需替换 `cs-sk-your-api-key-here` 为你的真实 API Key**，保存后重启客户端即可。

**Just replace `cs-sk-your-api-key-here` with your real API Key**, save and restart your client.

> 获取 API Key：在 Cherry Studio 中打开设置，找到 API 密钥并复制。
> Get API Key: Open Cherry Studio settings, find and copy the API key.

---

### 方式二：本地克隆运行 / Method 2: Clone and Run Locally

```bash
git clone https://github.com/Prism-Future/cherrystudio-knowledgebase-mcp.git
cd cherrystudio-knowledgebase-mcp
npm install
npm run build
```

然后使用本地路径配置：/ Then configure with local path:

```json
{
  "mcpServers": {
    "cherrystudio-knowledgebase": {
      "command": "node",
      "args": ["path/to/cherrystudio-knowledgebase-mcp/dist/index.js"],
      "env": {
        "CHERRYSTUDIO_API_BASE_URL": "http://127.0.0.1:23333",
        "CHERRYSTUDIO_API_KEY": "cs-sk-your-api-key-here"
      }
    }
  }
}
```

---

### 方式三：JSON 配置文件 / Method 3: JSON Config File

如果你不想把 API Key 写在客户端配置里，可以创建一个独立的 JSON 配置文件：

If you don't want to put the API Key in the client config, create a standalone JSON config file:

```bash
# 创建配置文件 / Create config file
echo '{"cherryStudioApiKey":"cs-sk-your-api-key-here"}' > config.json
```

然后客户端配置里不需要写 `env`：/ Then the client config doesn't need `env`:

```json
{
  "mcpServers": {
    "cherrystudio-knowledgebase": {
      "command": "npx",
      "args": ["-y", "cherrystudio-knowledgebase-mcp"]
    }
  }
}
```

配置文件支持放在以下位置（优先级由高到低）：/ Config file can be placed at (priority from high to low):
1. `config.json` in project root
2. `~/.config/cherrystudio-kb-mcp/config.json`

完整配置示例见 `config.example.json`。/ See `config.example.json` for full example.

---

## 前置要求 / Prerequisites

- Node.js 18+
- Cherry Studio（已启动并运行 / Running）
- Cherry Studio API 已启用且知道 API Key / API enabled and you have the API Key

---

## 功能 / Features

| 工具 / Tool | 功能 / Function |
|---|---|
| `listKnowledgeBases` | 列出所有知识库 / List all knowledge bases |
| `searchKnowledgeBases` | 搜索知识库内容 / Search knowledge bases |
| `getKnowledgeBase` | 获取知识库详情 / Get knowledge base details |
| `getMcpServers` | 列出已配置的 MCP 服务器 / List configured MCP servers |

---

## 常见问题 / FAQ

**Q: API Key 在哪里获取？/ Where to get the API Key?**

A: 在 Cherry Studio 设置中找到 API 密钥并复制。/ Find and copy the API key in Cherry Studio settings.

**Q: Cherry Studio API 地址是什么？/ What is the API address?**

A: 默认是 `http://127.0.0.1:23333`，请确保 Cherry Studio 正在运行。/ Default is `http://127.0.0.1:23333`, make sure Cherry Studio is running.

**Q: 支持哪些客户端？/ Which clients are supported?**

A: 任何支持 MCP 协议的客户端，如 Claude Desktop、Cursor、Codex 等。/ Any MCP-compatible client: Claude Desktop, Cursor, Codex, etc.

---

## 开发 / Development

```bash
npm install      # 安装依赖
npm run dev      # 开发模式
npm run build    # 构建
npm run test     # 测试
```

---

## 项目信息 / Project Info

- **作者 / Author**: [Prism-Future](https://github.com/Prism-Future)
- **许可证 / License**: MIT
- **技术栈 / Tech Stack**: TypeScript, Node.js, MCP SDK, Zod, Axios

---

## 相关链接 / Links

- [Cherry Studio 官网 / Official Site](https://docs.cherryai.com.cn/)
- [MCP 协议文档 / MCP Protocol Docs](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/)
- [问题反馈 / Issues](https://github.com/Prism-Future/cherrystudio-knowledgebase-mcp/issues)