WaniKani

wanikani-mcp

一个 MCP 服务，可只读访问用户的 WaniKani 数据。WaniKani 是一个用于学习日语汉字和词汇的间隔重复系统（SRS）。此服务提供六种工具，让 Claude 和其他 MCP 客户端查询用户的个人资料、课程／复习安排、SRS 任务、主题详情、复习统计数据和等级进度历史。

核心概念

• SRS（间隔重复系统） -- WaniKani 的核心学习机制。项目根据答对和答错的复习，在阶段 0（初始）到 9（已掌握）之间进阶。阶段越高，复习间隔越长。
• 主题 -- 用户学习的项目。共有四种类型：部首（构字部件）、汉字（字符）、词汇（多汉字词语）和假名词汇（仅由假名组成的词语）。每个主题都有释义、读音和记忆口诀。
• 任务 -- 跟踪用户对每个主题的 SRS 进度：当前阶段、解锁、开始、通过和掌握的时间。
• 课程 -- 新主题的介绍。满足前置条件后，主题即可作为课程学习。
• 复习 -- 定期进行的测验，用于测试记忆。答对会提升 SRS 阶段；答错则会使其退回。
• 等级 -- 用户在 WaniKani 中的总体进度（1--60）。升至新等级会解锁新主题。

架构

该服务分为三个层：读取配置并连接依赖项的入口点、注册工具并转换参数的 MCP 服务层，以及与 WaniKani API 通信的 HTTP 客户端。

graph TD
    MCP["MCP Client<br/>(Claude, etc.)"]
    SRV["MCP Server<br/>tool registration + formatting"]
    CLI["WaniKani API Client<br/>auth, pagination, typed responses"]
    API["WaniKani API<br/>api.wanikani.com/v2"]

    MCP -->|"stdio JSON-RPC"| SRV
    SRV --> CLI
    CLI -->|"HTTPS + Bearer auth"| API

该服务使用 mcp-go 处理 MCP 协议和 stdio 传输。WaniKani API 客户端使用 Go 泛型（Resource[T] 和 Collection[T]），为所有端点提供类型化访问，并自动处理分页。

数据流

sequenceDiagram
    participant C as MCP Client
    participant S as MCP Server
    participant A as WaniKani API

    C->>S: get_assignments(subjectTypes, limit, ...)
    S->>A: GET /v2/assignments?subject_types=...
    A-->>S: Page 1 (up to 500 items)

    opt More pages needed
        S->>A: GET next_url
        A-->>S: Page 2
    end

    S-->>C: "Showing N of M assignment(s):" + JSON

集合端点会自动分页。结果数量受可配置上限限制（默认 500，最大 10,000），并包含“Showing N of M”标题，以便客户端知道结果是否被截断。

入门指南

要求

• Go 1.27.3+（从源代码构建时需要）
• 来自 wanikani.com/settings/personal_access_tokens 的 WaniKani API token

安装

预构建的二进制文件可从 Releases 获取。

从源代码安装：

go install github.com/jbeshir/mcp-servers/wanikani/cmd/wanikani-mcp@latest

或者从仓库根目录构建：

make build

配置

变量	必填	默认值	说明
WANIKANI_API_KEY	是	--	来自 wanikani.com/settings/personal_access_tokens 的 Bearer token
WANIKANI_API_URL	否	https://api.wanikani.com	WaniKani API 的基础 URL 覆盖值

Claude Desktop

{
  "mcpServers": {
    "wanikani": {
      "command": "/path/to/wanikani-mcp",
      "env": {
        "WANIKANI_API_KEY": "your-api-token"
      }
    }
  }
}

Claude Code

claude mcp add wanikani -e WANIKANI_API_KEY=your-api-token /path/to/wanikani-mcp

工具

工具	说明	参数
get_user	获取已通过身份验证的用户个人资料，包括等级、订阅和假期状态	--
get_summary	获取按小时分组的可用课程和复习	--
get_assignments	获取跟踪主题在各个 SRS 阶段进度的 SRS 任务	subjectTypes、levels、srsStages、availableBefore、availableAfter、immediatelyAvailableForReview、immediatelyAvailableForLessons、limit
get_subjects	获取部首、汉字和词汇及其释义、读音和记忆口诀	types、levels、slugs、ids、limit
get_review_statistics	获取每个主题的复习准确率统计数据，包括答对／答错次数和连胜记录	subjectTypes、subjectIds、percentagesGreaterThan、percentagesLessThan、limit
get_level_progressions	获取用户在 WaniKani 各等级中的进度历史及时间戳	limit

所有工具均为只读。集合工具接受 limit 参数（默认值：500，最大值：10,000）。接受多个值的筛选参数使用逗号分隔的字符串（例如 "radical,kanji"）。