Kani MCP Server

Kani MCP サーバー

MCP クライアントから公式 API v2 を通じて、ユーザーの WaniKani の進捗状況と参照データにアクセスできる、小規模な読み取り専用の Model Context Protocol サーバーです。

次のような質問に回答できます。

• 今日、どのレビューとレッスンが予定されていますか？
• 指定したレベルには、どの漢字が割り当てられていますか？
• レビュー正答率が最も低い項目はどれですか？
• 保存したメモや同義語には何がありますか？

サーバーはローカルで stdio を介して動作します。データを保存せず、HTTP サービスを公開せず、WaniKani を変更しません。

要件

• Node.js 18 以降
• WaniKani API Tokens で作成した、読み取り専用権限の WaniKani 個人用アクセストークン

トークンは秘密にしてください。アカウントおよび学習データへのアクセスを許可するものです。

インストール

最も簡単な 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 で指定した、サポート対象のリソース 1 件

コレクションツールは API の 1 ページ分のデータを返します。続きのデータを取得するには、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 の個人用ベアラートークン
WANIKANI_API_BASE_URL	いいえ	API のルート。デフォルトは https://api.wanikani.com/v2 です

ベース URL を変更すると、ベアラートークンがそのホストに送信されます。リモートの上書き先には HTTPS を使用してください。テストおよびローカル開発では localhost の HTTP も使用できます。

開発

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

• npm run dev：TypeScript を stdio 経由で直接実行します
• 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のもとで利用でき、公開 npm レジストリに kani-mcp-server としてパッケージ化されています。GitHub のリリースでは、npm Trusted Publishing を通じて対応するパッケージバージョンが公開されます。一度限りのセットアップとリリース手順については、公開手順をご覧ください。

WaniKani は Tofugu LLC の商標です。この独立したプロジェクトは、WaniKani または Tofugu と提携、推奨、後援関係にありません。