Bunpro

bunpro-mcp

An MCP server that provides read-only access to Bunpro, a Japanese grammar and vocabulary SRS (spaced repetition system) platform. It exposes 12 tools for querying a user's profile, study statistics, review forecasts, JLPT progress, SRS stage details, and individual grammar point or vocabulary data. Authentication is handled automatically via Bunpro's Rails Devise login flow using your email and password.

Key Concepts

• SRS (Spaced Repetition System) -- Core learning mechanism. Items progress through stages: beginner, adept, seasoned, expert, master. Items answered incorrectly may become ghosts that reappear more frequently.
• Grammar Points -- Japanese grammar patterns (e.g. da "to be") with structure, meaning, nuance, and example sentences. Organized by JLPT level.
• Vocabulary -- Japanese words with readings, pitch accent patterns, frequency data, and JMDict dictionary entries.
• JLPT Levels -- Japanese Language Proficiency Test levels N5 (easiest) through N1 (hardest). Bunpro organizes all content by JLPT level.
• Decks -- Study collections with configurable batch sizes and daily lesson goals.
• Review Forecast -- Predicted number of upcoming reviews, viewable by day or by hour.

Architecture

The server has four layers: an entry point that reads configuration and obtains a token, an auth module that performs the Devise login flow when needed, an HTTP client that calls the Bunpro frontend API with Bearer token auth, and the MCP server that registers tools and formats responses.

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

Authentication happens once at startup. The auth module fetches a CSRF token from the login page, submits form-encoded credentials, and extracts the frontend_api_token cookie. The token has approximately a 2-day lifetime — long enough for any single MCP session.

Data Flow

The sequence diagram below shows both the startup token acquisition and a runtime tool call. All API requests are GET requests to api.bunpro.jp/api/frontend/* with the token sent as a Bearer authorization header.

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

Getting Started

Requirements

• Go 1.27.3+ (to build from source)
• A Bunpro account (free or paid)

Installation

Pre-built binaries are available from Releases.

Install from source:

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

Or build from the repo root:

make build

Configuration

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

Tools

All tools are read-only. No tool modifies Bunpro data.