cherrystudio-knowledgebase-mcp

v1.0.0

Published

a month ago

MCP Server for Cherry Studio Knowledge Base Integration

Downloads

0High
0Medium
0Low

prismsin

mcp cherrystudio knowledgebase ai

Cherry Studio Knowledge Base MCP Server

一个 MCP（Model Context Protocol）服务器，让 AI 助手能够访问和使用 Cherry Studio 的知识库。

An MCP (Model Context Protocol) server that enables AI assistants to access and use Cherry Studio knowledge bases.

功能特性 / Features

列出知识库 / List Knowledge Bases - 查看 Cherry Studio 中的所有知识库
搜索知识库 / Search Knowledge Bases - 跨一个或多个知识库进行搜索
获取详情 / Get Details - 查看特定知识库的详细信息
标准 MCP 协议 / Standard MCP Protocol - 支持任何 MCP 兼容的客户端

项目结构 / Project Structure

cherrystudio-knowledgebase-mcp/
├── src/
│   ├── index.ts              # 主入口文件 / Entry point
│   ├── server.ts             # MCP 服务器配置 / MCP Server config
│   ├── tools/                # 工具实现 / Tool implementations
│   ├── api/                  # API 客户端 / API client
│   └── config/               # 配置管理 / Configuration
├── package.json
├── tsconfig.json
├── .env.example              # 环境变量示例 / Env example
├── config.example.json       # JSON 配置示例 / JSON config example
└── README.md

快速开始 / Quick Start

前置要求 / Prerequisites

Node.js 18+
Cherry Studio（已启动并运行 / Running）
npm 或 yarn

安装步骤 / Installation

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

配置方式 / Configuration

本项目支持 两种配置方式，你可以任选其一：

This project supports two configuration methods. Choose the one you prefer:

方式一：JSON 配置文件（推荐）/ Method 1: JSON Config File (Recommended)

复制示例配置文件：

cp config.example.json config.json

编辑 config.json，填入你的 Cherry Studio API 密钥：

{
  "cherryStudioApiBaseUrl": "http://127.0.0.1:23333",
  "cherryStudioApiKey": "cs-sk-your-api-key-here",
  "requestTimeoutMs": 10000,
  "logLevel": "info"
}

提示：你也可以将配置文件放在全局位置 ~/.config/cherrystudio-kb-mcp/config.json，这样多个项目可以共用一份配置。

方式二：环境变量 / Method 2: Environment Variables

复制 .env.example 为 .env：

cp .env.example .env

编辑 .env 文件：

CHERRYSTUDIO_API_BASE_URL=http://127.0.0.1:23333
CHERRYSTUDIO_API_KEY=cs-sk-your-api-key-here

在 Claude Desktop 中配置 / Configure in Claude Desktop

打开 Claude Desktop 的配置文件：

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

添加以下配置（使用环境变量方式 / Using env method）：

{
  "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 配置文件方式 / Using JSON config method）：

{
  "mcpServers": {
    "cherrystudio-knowledgebase": {
      "command": "node",
      "args": [
        "path/to/cherrystudio-knowledgebase-mcp/dist/index.js"
      ]
    }
  }
}

注意：使用 JSON 配置文件方式时，确保 config.json 位于项目根目录，或放在 ~/.config/cherrystudio-kb-mcp/config.json。

重启 Claude Desktop 即可生效。

在 Cursor 中配置 / Configure in Cursor

打开 Cursor 设置 / Open Cursor Settings
找到 MCP 配置部分 / Find MCP configuration section
添加新的 MCP 服务器配置，参考上面的 JSON 格式

可用工具 / Available Tools

| 工具名称 / Tool Name | 描述 / Description | 参数 / Parameters | |---|---|---| | listKnowledgeBases | 列出所有知识库 / List all knowledge bases | 无 / None | | getKnowledgeBase | 获取知识库详情 / Get knowledge base details | id (string, required) | | searchKnowledgeBases | 搜索知识库 / Search knowledge bases | query (string, required) knowledgeBaseIds (string[], optional) documentCount (number, optional, default 10) | | getMcpServers | 列出 Cherry Studio 中配置的 MCP 服务器 / List MCP servers | 无 / None |

开发 / Development

npm run dev      # 开发模式 / Development mode
npm run watch    # 监听模式 / Watch mode
npm run build    # 构建 / Build
npm run test     # 测试 / Test

技术栈 / Tech Stack

TypeScript - 类型安全的 JavaScript / Type-safe JavaScript
Node.js - 运行时环境 / Runtime
@modelcontextprotocol/sdk - MCP 官方 SDK / Official MCP SDK
Zod - 输入验证 / Input validation
Axios - HTTP 客户端 / HTTP client

常见问题 / FAQ

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

A: 默认是 http://127.0.0.1:23333，请确保 Cherry Studio 正在运行且 API 已启用。

Q: 如何确认 Cherry Studio API 是否正常工作？/ How to verify Cherry Studio API is working?

A: 在浏览器中访问 http://127.0.0.1:23333/api-docs，如果看到 API 文档说明正常。

Q: 为什么 Claude Desktop 无法连接到 MCP 服务器？/ Why can't Claude Desktop connect?

A: 请检查：

项目路径是否正确 / Is the project path correct?
是否已运行 npm run build
配置是否正确（config.json 或 .env）/ Is config correct?
查看 Claude Desktop 的错误日志 / Check Claude Desktop error logs

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

A: 任何支持 MCP 协议的客户端，包括 Claude Desktop、Cursor 等。

贡献 / Contributing

欢迎提交 Issue 和 Pull Request！

许可证 / License

MIT License