Bunpro

bunpro-mcp

Bunpro への読み取り専用アクセスを提供する MCP サーバーです。Bunpro は日本語の文法と語彙を学ぶための SRS（間隔反復システム）プラットフォームです。ユーザーのプロフィール、学習統計、復習の予測、JLPT の進捗状況、SRS ステージの詳細、個々の文法項目や語彙データを照会するための 12 個のツールを公開します。認証は、メールアドレスとパスワードを使って Bunpro の Rails Devise ログインフローを通じて自動的に行われます。

主な概念

• SRS（間隔反復システム） -- 学習の中心となる仕組みです。項目は、初級者、熟達者、経験者、エキスパート、マスターの各ステージへと進みます。誤答した項目はゴーストになり、より頻繁に再び出題されることがあります。
• 文法項目 -- 構造、意味、ニュアンス、例文を含む日本語の文法パターン（例：da「である」）です。JLPT レベル別に整理されています。
• 語彙 -- 読み、ピッチアクセントのパターン、頻度データ、JMDict の辞書項目を含む日本語の単語です。
• JLPT レベル -- 日本語能力試験のレベルです。最も易しい N5 から最も難しい N1 まであります。Bunpro では、すべてのコンテンツが JLPT レベル別に整理されています。
• デッキ -- バッチサイズと毎日のレッスン目標を設定できる学習コレクションです。
• 復習予測 -- 今後の復習件数の予測です。日単位または時間単位で確認できます。

アーキテクチャ

サーバーは 4 つのレイヤーで構成されています。設定を読み込んでトークンを取得するエントリーポイント、必要に応じて Devise のログインフローを実行する認証モジュール、Bearer トークン認証で Bunpro フロントエンド API を呼び出す HTTP クライアント、そしてツールを登録して応答を整形する MCP サーバーです。

graph TD
    MCP["MCP Client<br/>(Claude, etc.)"]
    SRV["MCP Server<br/>12 read-only tools"]
    CLI["HTTP Client<br/>Bearer token auth"]
    API["Bunpro Frontend API<br/>api.bunpro.jp"]

    MCP -->|"stdio JSON-RPC"| SRV
    SRV --> CLI
    CLI -->|"GET /api/frontend/*"| API

    subgraph "Authentication (startup)"
        direction LR
        LOGIN["Auth Module<br/>Devise login flow"]
        SITE["bunpro.jp<br/>Rails login page"]
        LOGIN -->|"CSRF + POST credentials"| SITE
        SITE -->|"frontend_api_token cookie"| LOGIN
    end

    LOGIN -.->|"token"| CLI

認証は起動時に一度だけ行われます。認証モジュールはログインページから CSRF トークンを取得し、フォームエンコードされた認証情報を送信して、frontend_api_token Cookie を抽出します。トークンの有効期間は約 2 日間で、単一の MCP セッションには十分な長さです。

データフロー

以下のシーケンス図は、起動時のトークン取得と実行時のツール呼び出しの両方を示しています。すべての API リクエストは api.bunpro.jp/api/frontend/* への GET リクエストで、トークンは Bearer 認証ヘッダーで送信されます。

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Auth as Auth Module
    participant Site as bunpro.jp
    participant API as api.bunpro.jp

    Note over Client,API: Startup: Token Acquisition
    Server->>Auth: Login(email, password)
    Auth->>Site: GET /login
    Site-->>Auth: HTML with CSRF token
    Auth->>Site: POST /users/sign_in (form-encoded)
    Site-->>Auth: frontend_api_token cookie
    Auth-->>Server: token

    Note over Client,API: Runtime: Tool Calls
    Client->>Server: get_grammar_point(id)
    Server->>API: GET /api/frontend/reviewables/grammar_point/{id}
    Note over Server,API: Authorization: Bearer token
    API-->>Server: JSON:API response
    Server-->>Client: Formatted JSON result

はじめに

要件

• Go 1.27.3 以降（ソースからビルドする場合）
• Bunpro アカウント（無料または有料）

インストール

ビルド済みバイナリは リリース から入手できます。

ソースからインストールする場合：

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

または、リポジトリのルートからビルドします：

make build

設定

変数	必須	説明
BUNPRO_EMAIL	はい	Bunpro アカウントのメールアドレス
BUNPRO_PASSWORD	はい	Bunpro アカウントのパスワード
BUNPRO_API_URL	いいえ	API のベース URL（デフォルト：https://api.bunpro.jp）
BUNPRO_LOGIN_URL	いいえ	ログインページの URL（デフォルト：https://bunpro.jp）

Claude Desktop

{
  "mcpServers": {
    "bunpro": {
      "command": "/path/to/bunpro-mcp",
      "env": {
        "BUNPRO_EMAIL": "[email protected]",
        "BUNPRO_PASSWORD": "your-password"
      }
    }
  }
}

Claude Code

claude mcp add bunpro /path/to/bunpro-mcp -e [email protected] -e BUNPRO_PASSWORD=your-password

ツール

すべてのツールは読み取り専用です。Bunpro のデータを変更するツールはありません。

ツール	パラメーター	説明
get_user	--	ユーザープロフィール：レベル、XP、連続学習日数、サブスクリプションの状態
get_study_queue	--	復習期限を迎えた文法と語彙の件数
get_decks	--	デッキ設定：1日の目標、進捗、バッチサイズ
get_stats	--	学習統計：学習日数、連続学習日数、正答率、バッジ
get_jlpt_progress	--	SRS ステージ別の件数を含む JLPT N5〜N1 の進捗
get_review_forecast	granularity（任意）："daily" または "hourly"	文法と語彙に分けた今後の復習予定
get_srs_overview	--	SRS レベル別の合計件数（初級からマスターまで、およびゴーストと自主学習）
get_review_activity	--	過去約30日間の日ごとの復習件数
get_grammar_srs_details	level（必須）：beginner、adept、seasoned、expert、master のいずれか；page（任意）	特定の SRS レベルにある、ページ分けされた文法の復習項目
get_vocab_srs_details	level（必須）：beginner、adept、seasoned、expert、master のいずれか；page（任意）	特定の SRS レベルにある、ページ分けされた語彙の復習項目
get_grammar_point	id（必須）	文法項目の詳細：意味、構造、ニュアンス、学習問題
get_vocab	slug_or_id（必須）：スラッグ（例：「食べる」）または数値 ID	語彙の詳細：読み、ピッチアクセント、頻度、JMDict エントリー