Bunpro MCP Server

Bunpro MCP

A read-only Model Context Protocol server that lets MCP clients work with your Bunpro profile, review queue, forecasts, SRS progress, vocabulary, learning content, and search.

[!WARNING] This project uses Bunpro's unofficial, reverse-engineered frontend API. It may change without notice. This project is not affiliated with or endorsed by Bunpro.

What you can do

• Ask for your profile, due count, review queue, or current quiz questions.
• Inspect JLPT progress, SRS levels, forecasts, activity, and last-session accuracy.
• Search Bunpro grammar and vocabulary with compact results.
• Retrieve vocabulary details and notes, deck learning content, or topic replies.

The server exposes no account-changing, review-submission, or deletion tools.

Requirements

• A Bunpro account and a current frontend bearer token.
• Node.js 22 or newer when running from source or through npx.
• An MCP client that supports local stdio servers.

Get your Bunpro token

1. Sign in to Bunpro in your browser.
2. Open the browser developer tools and select Network.
3. Select a request to https://api.bunpro.jp/api/frontend/....
4. Copy the Authorization request header value without the Bearer prefix.

Treat this token like a password. Do not commit it, paste it into issues, or expose it in screenshots.

Configure an MCP client

Install and launch the published package directly from your MCP client:

{
  "mcpServers": {
    "bunpro": {
      "command": "npx",
      "args": ["-y", "bunpro-mcp-server"],
      "env": { "BUNPRO_API_TOKEN": "your-token" }
    }
  }
}

For local development, build the repository and configure the client with an absolute path:

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

Restart the MCP client after changing its configuration or rebuilding the server.

Run locally

npm ci
npm run build
BUNPRO_API_TOKEN='your-token' node dist/index.js

The last command starts an MCP stdio process and waits for protocol messages; it has no interactive prompt. Prefer the MCP client's environment configuration so the token does not enter shell history.

Example requests

• “Show my Bunpro profile.”
• “How many reviews are due?”
• “Show my hourly review forecast.”
• “Search Bunpro vocabulary for 日本語.”
• “What was my last review-session accuracy?”

Available tools

Exact inputs, outputs, defaults, and errors are in MCP contracts.

Configuration

Development

npm ci
npm run check

Authenticated live checks are separate:

cp .env.example .env
# Edit .env locally, then:
npm run test:live

The live suite is read-only and .env is ignored. See Testing and Contributing.

Troubleshooting

• BUNPRO_API_TOKEN is required: provide it in the MCP client configuration and restart the client.
• Bunpro API 401 or 403: obtain a fresh token and omit the Bearer prefix.
• Tool list did not change after rebuilding: restart the MCP client.
• 404 or 5xx from Bunpro: the unofficial endpoint may have changed; run live tests and open a sanitized issue.
• No output when launched in a terminal: expected; stdio is waiting for an MCP host.

Architecture and limitations

The server is a local stdio package using the official TypeScript MCP SDK. Most outputs pass through Bunpro's JSON, so upstream shape changes are possible. It currently provides tools only—no resources, prompts, hosted HTTP endpoint, browser login, or OAuth flow.

Read Architecture, Technical security, and the community API reference.

Releases and distribution

The npm package is published as bunpro-mcp-server and can be launched with npx -y bunpro-mcp-server. Release metadata is also prepared for the official MCP Registry through server.json.

Releases use Semantic Versioning and GitHub Releases. The release tag must match v<package version>; GitHub Actions then tests, publishes through tokenless npm Trusted Publishing, and registers the same version in the official MCP Registry. See Publishing.

A future hosted streamable-HTTP server could reduce installation friction, but it first needs secure per-user authentication and token storage. Local stdio keeps the current bearer token on the user's machine.

Security, contributions, and license

Read SECURITY.md before reporting a vulnerability. Contributions follow CONTRIBUTING.md. Never include credentials or personal Bunpro responses in a report.

Licensed under the existing MIT License. Downstream users must also comply with Bunpro's applicable terms and policies.