Bunpro MCP Server

Bunpro MCP

一个只读的 Model Context Protocol 服务，可让 MCP 客户端使用你的 Bunpro 个人资料、复习队列、预测、SRS 进度、词汇、学习内容和搜索功能。

警告

本项目使用 Bunpro 非官方的逆向工程前端 API。该 API 可能随时变更，恕不另行通知。本项目与 Bunpro 无关，也未获得 Bunpro 认可。

你可以做什么

• 查询个人资料、待复习数量、复习队列或当前测验题目。
• 查看 JLPT 进度、SRS 等级、预测、活动记录和上次复习的准确率。
• 搜索 Bunpro 语法和词汇，并获取精简结果。
• 获取词汇详情和笔记、牌组学习内容或主题回复。

此服务不提供任何更改账户、提交复习或删除的工具。

要求

• 一个 Bunpro 账户和当前有效的前端 bearer token。
• 从源代码运行或通过 npx 运行时，需要 Node.js 22 或更高版本。
• 支持本地 stdio 服务的 MCP 客户端。

获取 Bunpro token

1. 在浏览器中登录 Bunpro。
2. 打开浏览器开发者工具并选择 Network。
3. 选择一个发往 https://api.bunpro.jp/api/frontend/... 的请求。
4. 复制 Authorization 请求标头的值，并去掉 Bearer 前缀。

请像对待密码一样保管此 token。不要将其提交到代码库、粘贴到问题帖中，也不要在截图中暴露。

配置 MCP 客户端

直接从 MCP 客户端安装并启动已发布的软件包：

{
  "mcpServers": {
    "bunpro": {
      "command": "npx",
      "args": ["-y", "bunpro-mcp-server"],
      "env": { "BUNPRO_API_TOKEN": "your-token" }
    }
  }
}

若要进行本地开发，请构建代码库，并使用绝对路径配置客户端：

{
  "mcpServers": {
    "bunpro": {
      "command": "node",
      "args": ["/absolute/path/to/bunpro-mcp-server/dist/index.js"],
      "env": { "BUNPRO_API_TOKEN": "your-token" }
    }
  }
}

更改配置或重新构建服务后，请重启 MCP 客户端。

在本地运行

npm ci
npm run build
BUNPRO_API_TOKEN='your-token' node dist/index.js

最后一条命令会启动一个 MCP stdio 进程，并等待协议消息；它没有交互式提示符。建议使用 MCP 客户端的环境配置，以免 token 进入 shell 历史记录。

请求示例

• “显示我的 Bunpro 个人资料。”
• “有多少项待复习？”
• “显示我的每小时复习预测。”
• “搜索 Bunpro 中的 日本語 词汇。”
• “我上次复习的准确率是多少？”

可用工具

工具	用途
get_user	获取当前用户个人资料。
get_user_furigana	获取振假名设置。
get_due	获取当前到期项目。
get_queue	获取当前复习队列。
get_quiz_questions	获取当前只读测验队列。
get_base_stats	获取基础学习统计数据。
get_jlpt_progress	获取综合 JLPT 进度。
get_daily_forecast	获取每日复习预测。
get_hourly_forecast	获取每小时复习预测。
get_srs_overview	获取 SRS 等级概览。
get_review_activity	获取每日或每小时复习活动。
get_last_session	获取上次复习的准确率。
get_weak_items	根据学习次数和准确率对薄弱的语法和词汇进行排序。
get_vocab	根据 slug 或 ID 获取词汇。
get_vocab_notes	获取词汇笔记。
get_vocab_neighbors	获取牌组中相邻的词汇。
get_learning_content	获取牌组的学习内容。
get_topic_replies	获取 Bunpro 讨论主题的回复。
get_srs_level_details	获取分页的 SRS 等级详情。
get_self_study_srs_details	获取分页的自学 SRS 详情。
get_ghost_srs_details	获取幽灵复习 SRS 详情。
search	搜索语法和词汇，并返回精简结果。

具体的输入、输出、默认值和错误信息请参阅 MCP contracts。

配置

变量	必需	描述
BUNPRO_API_TOKEN	是	不带 Bearer 前缀的前端 bearer token。
BUNPRO_API_BASE_URL	否	主要用于测试的 API 覆盖地址。token 会发送到该地址；请仅使用可信 URL。

开发

npm ci
npm run check

经过身份验证的在线检查需单独运行：

cp .env.example .env
# Edit .env locally, then:
npm run test:live

在线测试套件为只读，且 .env 已被忽略。请参阅测试和贡献指南。

故障排除

• BUNPRO_API_TOKEN is required： 在 MCP 客户端配置中提供该令牌，然后重启客户端。
• Bunpro API 401 或 403： 获取新令牌，并省略 Bearer 前缀。
• 重新构建后工具列表没有变化： 重启 MCP 客户端。
• Bunpro 返回 404 或 5xx： 非官方端点可能已发生变化；运行实时测试并提交经过脱敏的问题报告。
• 在终端中启动后没有输出： 这是预期行为；标准输入/输出正在等待 MCP 主机连接。

架构和限制

该服务是一个使用官方 TypeScript MCP SDK 的本地标准输入/输出包。大多数输出直接传递 Bunpro 的 JSON，因此上游数据结构可能发生变化。目前它仅提供工具，不提供资源、提示词、托管的 HTTP 端点、浏览器登录或 OAuth 流程。

请阅读架构、技术安全和社区 API 参考。

发布和分发

npm 包以 bunpro-mcp-server 发布，可通过 npx -y bunpro-mcp-server 启动。发布元数据也会通过 server.json 为官方 MCP Registry准备。

发布遵循语义化版本规范，并通过 GitHub Releases 发布。发布标签必须与 v<package version> 一致；随后，GitHub Actions 会运行测试，通过无需令牌的 npm Trusted Publishing 发布，并在官方 MCP Registry 中注册相同版本。请参阅发布说明。

未来的托管式可流式传输 HTTP 服务或许能降低安装难度，但首先需要安全地实现每位用户的身份验证和令牌存储。本地标准输入/输出模式可将当前的 bearer 令牌保存在用户的设备上。

安全、贡献和许可证

报告漏洞前，请阅读 SECURITY.md。贡献请遵循 CONTRIBUTING.md。报告中切勿包含凭据或 Bunpro 个人响应内容。

本项目沿用现有的 MIT License。下游用户也必须遵守 Bunpro 适用的条款和政策。