chinese-corpus-mcp

中文语料平台的官方 MCP（Model Context Protocol）服务器（Python 版）。接入后，你的 AI 助手（Claude、Cursor、其他 MCP 客户端）可以直接检索平台授权语料、发起深度研究、查询全平台图书元数据。

与 npm 版 @chinese-corpus/mcp-server 是同一产品的两种语言实现，功能完全对等：二选一安装即可——机器上有 Python 用本包（uvx 直跑，无需安装 Node.js），有 Node.js 用 npm 版。

五个工具

数据集范围由你的 API Key 在平台侧决定：工具参数、环境变量、配置文件里都没有（也不允许有）"选数据集"的开关。要换数据集，去平台网站「用户中心 → API Key 管理」切换当前绑定即可，下一次调用立即生效，MCP 服务器无需重启、无需改配置。

安装（推荐：一句话让 AI 助手帮你装）

需要 Python 3.11+ 与 uv（curl -LsSf https://astral.sh/uv/install.sh | sh）。把下面这段话原样发给你的 AI 助手（Claude / Cursor 等），它会帮你完成安装和配置：

请帮我安装中文语料平台的 MCP 服务器：在终端运行 uvx chinese-corpus-mcp --help 确认可用（需要 Python 3.11+ 与 uv），然后把它注册为 MCP 服务器（命令 uvx，参数 chinese-corpus-mcp，环境变量 CHINESE_CORPUS_API_KEY，值我会单独提供）。全部工具（chunk_search / deep_research / deep_research_status / book_search / get_service_context）都启用，不需要任何启动参数。

不想用 AI 助手？也可以先安装再配置：pipx install chinese-corpus-mcp（或 pip install chinese-corpus-mcp），然后命令填 chinese-corpus-mcp。uvx 形态免安装、卸载即删配置，对系统侵入最小。

手动配置

Claude Desktop / 标准 MCP 客户端（单服务器）

在 MCP 配置文件（如 claude_desktop_config.json）中加入：

{
  "mcpServers": {
    "chinese-corpus": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": {
        "CHINESE_CORPUS_API_KEY": "ck_你的APIKey"
      }
    }
  }
}

环境变量

没有 dataset / datasetId 环境变量——数据集选择永远在平台后台完成（见上文）。本服务器默认不读取 HTTP_PROXY 等代理环境变量（默认地址是内网入口，走代理反而连不上）；需要代理的自定义部署请联系平台方。

Cursor / 其他客户端

任何支持"命令 + 环境变量"形态 MCP 服务器的客户端都适用：命令 uvx + 参数 chinese-corpus-mcp，环境变量同上表。

进阶：一台机器多个服务器条目

默认一把 Key 对应一个服务器条目已够用（换数据集在后台切换，见上）。仅当你需要同时保持两个不同数据集在线时，才注册多个条目，并用 CHINESE_CORPUS_PROFILE_NAME 区分：

{
  "mcpServers": {
    "chinese-corpus-全库": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": { "CHINESE_CORPUS_API_KEY": "ck_key_a", "CHINESE_CORPUS_PROFILE_NAME": "全库" }
    },
    "chinese-corpus-古籍库": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": { "CHINESE_CORPUS_API_KEY": "ck_key_b", "CHINESE_CORPUS_PROFILE_NAME": "古籍库" }
    }
  }
}

提示：本包与 npm 版是同一产品身份，命令名相同（chinese-corpus-mcp）。uvx / npx 直跑形态互不安装、互不冲突；只有当你把两个包都"全局安装"到同一台机器时，才需要留意 PATH 中谁在前——一般用不到这种组合。

常见问题

• 返回「API Key 无效或已过期」：检查 CHINESE_CORPUS_API_KEY 是否配置、Key 是否仍为 ACTIVE 且未过期、是否被吊销。
• 返回「积分不足」：到平台网站充值后重试；余额与消费记录在个人中心查询（工具不返回余额）。
• 返回「无权访问此 Key 绑定的数据集」：数据集已下架或归属变更；到用户中心切换绑定数据集。
• 想换检索的图书范围：不是改 MCP 配置——去平台「用户中心 → API Key 管理」切换 Key 的当前绑定数据集，下一次调用生效，无需重启。
• deep_research 超时：任务不会被取消，稍后用 deep_research_status（带返回的 taskId）取回报告。
• book_search 翻页：返回的 count 是本页条数，不是命中总数；按 page/pageSize 翻页（最多第 10 页）。

日志与排障

MCP 服务器按协议要求只把 JSON-RPC 帧写到 stdout；运行日志全部走 stderr（不会干扰客户端解析）。排障时看客户端的 MCP 日志面板即可，报错文本带「请求编号」，反馈给平台时可一并附上。

许可证

MIT（见 LICENSE）。