Kani MCP Server

Kani MCP Server

一个小型、只读的 Model Context Protocol 服务，通过官方 API v2 让 MCP 客户端访问用户的 WaniKani 学习进度和 WaniKani 参考数据。

它可以回答以下问题：

• 今天有哪些即将到来的复习和课程？
• 指定等级分配了哪些汉字？
• 哪些学习项目的复习准确率最低？
• 我保存了哪些备注或同义词？

该服务通过 stdio 在本地运行。它不会存储数据、提供 HTTP 服务或修改 WaniKani。

要求

• Node.js 18 或更高版本
• 具有只读权限的 WaniKani 个人访问令牌，可在 WaniKani API Tokens 中创建

请妥善保管令牌。它可以访问账户和学习数据。

安装

最简单的 MCP 配置是使用 npx 直接运行已发布的包：

{
  "mcpServers": {
    "wanikani": {
      "command": "npx",
      "args": ["-y", "kani-mcp-server@latest"],
      "env": {
        "WANIKANI_API_TOKEN": "your-read-only-token"
      }
    }
  }
}

或者，全局安装可执行文件：

npm install --global kani-mcp-server
kani-mcp-server

更改配置后，请重启 MCP 客户端。如有可用的安全密钥功能，请优先使用它，而不要将令牌写入 JSON 文件。

从源代码运行

git clone https://github.com/Alexxanddr/kani-mcp-server.git
cd kani-mcp-server
npm ci
cp .env.example .env
# Edit .env and set WANIKANI_API_TOKEN.
npm run build
node --env-file=.env dist/index.js

若要为源代码检出版本配置 MCP 客户端，请替换路径和令牌：

{
  "mcpServers": {
    "wanikani": {
      "command": "node",
      "args": ["/absolute/path/to/kani-mcp-server/dist/index.js"],
      "env": {
        "WANIKANI_API_TOKEN": "your-read-only-token"
      }
    }
  }
}

进程通过 stdin/stdout 使用 MCP 通信，因此启动后终端没有输出属于正常情况。

工具

工具	用途
get_user	用户资料、等级、偏好设置和订阅状态
get_summary	接下来 24 小时内可进行的课程和复习
list_assignments	按学习项目、等级、SRS 阶段或状态筛选分配项目
list_subjects	部首、汉字、词汇和假名词汇
list_review_statistics	按学习项目统计准确率和错误答案总数
list_reviews	已完成的复习记录
list_study_materials	个人备注以及释义/读音同义词
list_level_progressions	等级进度记录
list_resets	账户重置记录
list_spaced_repetition_systems	SRS 阶段定义
list_voice_actors	发音配音演员元数据
get_resource	按类型和数字 ID 获取一个受支持的资源

集合工具每次返回一页 API 数据。使用 WaniKani 集合分页数据中的 page_after_id 或 page_before_id 继续获取。数组会作为 API 预期的逗号分隔筛选条件发送。

提示词示例：

Show my WaniKani level and the reviews due in the next 24 hours.
List my level 10 kanji assignments and explain their current SRS stages.
Find review statistics below 70%, then fetch the matching subjects.

有关确切的输入和输出，请参阅 MCP 合约。

配置

变量	必需	含义
WANIKANI_API_TOKEN	是	WaniKani API v2 个人 bearer 令牌
WANIKANI_API_BASE_URL	否	API 根地址；默认为 https://api.wanikani.com/v2

更改基础 URL 会将 bearer 令牌发送到该主机。远程覆盖地址必须使用 HTTPS；测试和本地开发可使用 localhost HTTP。

开发

npm ci
npm run check
npm pack --dry-run

• npm run dev：通过 stdio 直接运行 TypeScript
• npm test：运行单元测试和 MCP 合约测试
• npm run type-check：检查 TypeScript，不生成文件
• npm run build：在 dist/ 中创建捆绑的可执行文件

修改公开工具前，请阅读 CONTRIBUTING.md、架构和测试。

故障排除

• WANIKANI_API_TOKEN is required：在 MCP 客户端的 env 块中传入该变量，或使用 --env-file=.env 启动 Node。
• 401 Unauthorized：检查令牌；如果令牌可能已泄露，请重新创建。
• 429 Too Many Requests：等待 WaniKani 的速率限制重置，并缩小请求集合的范围。
• 响应过大：添加筛选条件并分页，而不是请求范围过大的学习项目或复习记录。
• 客户端显示已断开：使用绝对脚本路径，运行 npm run build，并确认客户端的 PATH 中包含 Node 18+。

限制

• 只读：本项目有意不提供开始作业、提交复习、修改用户设置和编辑学习材料的功能。
• 不提供自动多页聚合、缓存、资源或提示词。
• API 响应对象会原样传递，因此上游新增的内容无需发布新版本即可显示。

许可证和分发

本项目采用 MIT License，并以 kani-mcp-server 的名称发布到公共 npm registry。GitHub releases 会通过 npm Trusted Publishing 发布对应版本的软件包；一次性设置和发布流程请参阅发布说明。

WaniKani 是 Tofugu LLC 的商标。本独立项目与 WaniKani 或 Tofugu 无关联，也未获得其认可或赞助。