Bunpro MCP Server

Bunpro MCP

MCP クライアントから Bunpro のプロフィール、復習キュー、予測、SRS の進捗、語彙、学習コンテンツ、検索を利用できる、読み取り専用の Model Context Protocol サーバーです。

警告

このプロジェクトでは、Bunpro の非公式なリバースエンジニアリング済みフロントエンド API を使用しています。予告なく変更される場合があります。このプロジェクトは Bunpro とは提携しておらず、Bunpro による承認も受けていません。

できること

• プロフィール、期限が来た項目数、復習キュー、現在のクイズ問題を確認できます。
• JLPT の進捗、SRS レベル、予測、アクティビティ、直近のセッションの正答率を確認できます。
• Bunpro の文法と語彙を、簡潔な結果で検索できます。
• 語彙の詳細やメモ、デッキの学習コンテンツ、トピックへの返信を取得できます。

アカウントの変更、復習の送信、削除を行うツールは公開していません。

要件

• Bunpro アカウントと、現在のフロントエンドのベアラートークンが必要です。
• ソースから実行する場合、または npx を使用する場合は、Node.js 22 以降が必要です。
• ローカルの stdio サーバーに対応した MCP クライアントが必要です。

Bunpro トークンを取得する

1. ブラウザーで Bunpro にサインインします。
2. ブラウザーの開発者ツールを開き、Network を選択します。
3. https://api.bunpro.jp/api/frontend/... へのリクエストを選択します。
4. Bearer のプレフィックスを除いた Authorization リクエストヘッダーの値をコピーします。

このトークンはパスワードと同様に扱ってください。コミットしたり、課題に貼り付けたり、スクリーンショットで公開したりしないでください。

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 クライアントの環境設定を使用してください。

リクエストの例

• 「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	スラッグまたは 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 コントラクトを参照してください。

設定

変数	必須	説明
BUNPRO_API_TOKEN	はい	Bearer のプレフィックスを除いたフロントエンドのベアラートークンです。
BUNPRO_API_BASE_URL	いいえ	主にテスト用の API オーバーライドです。トークンが渡されるため、信頼できる 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： 非公式エンドポイントが変更された可能性があります。ライブテストを実行し、サニタイズした Issue を作成してください。
• ターミナルで起動しても出力がない： 想定どおりです。stdio は MCP ホストからの接続を待機しています。

アーキテクチャと制限事項

このサーバーは、公式の TypeScript MCP SDK を使用するローカルの stdio パッケージです。出力の大部分は Bunpro の JSON をそのまま渡すため、上流のデータ構造が変更される可能性があります。現在提供しているのはツールのみで、リソース、プロンプト、ホスト型 HTTP エンドポイント、ブラウザーでのログイン、OAuth フローはありません。

アーキテクチャ、技術的なセキュリティ、およびコミュニティ API リファレンスをお読みください。

リリースと配布

npm パッケージは bunpro-mcp-server として公開されており、npx -y bunpro-mcp-server で起動できます。公式 MCP Registryへの登録に向けたリリースメタデータも、server.json を通じて準備されています。

リリースではセマンティック バージョニングと GitHub Releases を使用します。リリースタグは v<package version> と一致する必要があります。一致すると、GitHub Actions がテストを実行し、トークンレスの npm Trusted Publishing を通じて公開し、同じバージョンを公式 MCP Registry に登録します。公開手順をご覧ください。

将来的にホスト型のストリーミング可能な HTTP サーバーを導入すれば、インストールの手間を減らせる可能性があります。ただし、まずユーザーごとの安全な認証とトークン保管が必要です。ローカル stdio 方式では、現在のベアラートークンをユーザーのマシン上に保持します。

セキュリティ、コントリビューション、ライセンス

脆弱性を報告する前に、SECURITY.mdをお読みください。コントリビューションはCONTRIBUTING.mdに従ってください。報告に認証情報や個人の Bunpro 応答を含めないでください。

既存のMIT Licenseに基づいてライセンスされています。下流のユーザーも、Bunpro に適用される規約とポリシーを遵守する必要があります。