bunpro-mcp

An unofficial Model Context Protocol server for Bunpro, the Japanese grammar/vocabulary SRS. It exposes Bunpro's review queue, search, statistics, and SRS management as MCP tools, so an LLM agent can read your study data and add grammar points / vocabulary to your reviews.

Disclaimer — please read

This is an independent, unofficial project, not affiliated with, endorsed by, or supported by Bunpro. It wraps Bunpro's private, undocumented frontend API, which can change or break at any time. Built for personal, educational use.

This tool only works because it relies on Bunpro's servers, content, and services. Your use of it — and especially any commercial use — is subject to Bunpro's Terms of Service independently of this project's license. No Bunpro content (grammar explanations, example sentences, vocabulary data, audio) is included in this repository. Use at your own risk. If you build something commercial on top of Bunpro, support Bunpro directly.

Features

• Read your review queue, due counts, SRS overview, JLPT progress, forecasts, and session history.

• Search grammar points and vocabulary — compact results, filterable by type, size-capped.

• Add / remove grammar points and vocabulary to / from your SRS reviews.

• Manage bookmarks.

• Per-call token resolution: refresh an expired token without restarting your MCP client (see below).

Related MCP server: TalkToAnki

Requirements

• Node.js 18+ (uses the built-in fetch).

• A Bunpro account and its frontend_api_token.

Getting your token

The frontend API uses the frontend_api_token cookie as a bearer token:

1. Log in to bunpro.jp.

2. DevTools → Application → Cookies → https://bunpro.jp → copy the value of frontend_api_token.

The token expires roughly monthly; refresh it the same way when calls start returning 401 AUTH_USER_DENIED.

Install & build

npm install
npm run build

Configure your MCP client

Add the server to your MCP client config (stdio transport). Build it locally first (npm install builds via the prepare script), then point at dist/index.js — see claude_desktop_config.example.json:

{
  "mcpServers": {
    "bunpro": {
      "command": "node",
      "args": ["/absolute/path/to/bunpro-mcp/dist/index.js"],
      "env": { "BUNPRO_API_TOKEN": "your_frontend_api_token_here" }
    }
  }
}

Not yet published to npm. Once it is, you'll also be able to run it with no local clone via "command": "npx", "args": ["-y", "@patvandyke/bunpro-mcp"].

BUNPRO_API_KEY (legacy) is optional and only enables the two *_legacy tools.

Token refresh without restarting

The token is resolved per request, not just at startup, so a refreshed token is picked up without restarting the server:

1. BUNPRO_TOKEN_FILE — if set (or, by default, ~/.claude-work/.claude.json when present), the live BUNPRO_API_TOKEN value is read from that JSON file on each call (30 s cache) and re-read on a 401. Refresh the token in the file and the next call picks it up — no restart. This is handy under Claude Code, whose config already holds the token.

2. Otherwise it falls back to the BUNPRO_API_TOKEN env var supplied at spawn.

A 401 returns a clear "token expired" message instead of dropping the connection.

Tools

API notes

• Frontend API base: https://api.bunpro.jp/api/frontend. Auth: Authorization: Bearer <frontend_api_token>.

• The reviews endpoint uses the type names Vocab / GrammarPoint (bookmarks use Vocabulary / GrammarPoint).

• Raw search responses can be very large; this server returns a compact projection and reports truncation.

Related projects

• brimalval/bunpro-mcp — an independent Python / FastAPI implementation.

License

MIT © Patrik Kollár. Keep the copyright / credit notice in copies. This license covers this client code only — it grants no rights to Bunpro's services or content, which remain governed by Bunpro's Terms of Service.