What can you do with this server?

The bunpro-mcp server manages a Japanese-learning spaced-repetition review queue backed by Markdown notes, accessible via a conversational AI interface. * Get your review queue: Retrieve grammar points and vocabulary most in need of review, ordered by priority, with retrievability scores, days since review, lapse counts, and past mistake notes. * Get a practice pool: Fetch already-mastered items for active-use practice (e.g., conversation scenarios) — the opposite of the review queue, returning your strongest-known items. * Look up a specific item: Retrieve full details about any grammar point or vocabulary word, including personal vault notes, memory state, reading, meaning, and JLPT level. * Submit grades after a session: Record performance (grades 1–4) with optional error notes so the spaced-repetition schedule updates accordingly. * Add a new item: File a newly encountered grammar point or vocabulary word with reading, meaning, JLPT level, tags, and an optional starting progress level (e.g., Beginner through Master). * Import a Bunpro CSV export: Bulk-load items from a Bunpro CSV export into the vault, with a dry-run mode to preview changes before committing.

Which integrations are available for this server?

Manages a Japanese-learning review queue using an Obsidian vault as the backing store, allowing notes for grammar and vocabulary to be stored and reviewed in Obsidian.

How do I use bunpro-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@bunpro-mcp quiz me on what's due" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

bunpro-mcp

by Muslinmin

Overview Schema Related Servers Score Discussions

Python

Local

bunpro-mcp

An MCP server that manages a Japanese-learning review queue backed by a folder of Markdown notes. It runs on Cloud Run and connects to Claude on web, mobile, and desktop — so reviews work from a phone — while the notes stay plain .md files you can read in Obsidian.

For contributors: see .agent/ARCHITECTURE.md for the build rationale and .agent/CONTRACT.md for the data shapes and tool behaviour.

What you can do with it

Ask Claude in plain language — it picks the right tool:

Review what you're forgetting — "quiz me on what's due" pulls the items most in need of review and updates your schedule based on how you do.
Practice words you've already mastered — "test me on food words I already know" gathers solid items around a theme, proposes a short practice conversation, runs it, then records how it went.
Add something new — "I just learned 〜てしまう" files it, filling in the reading, meaning, and JLPT level for you.
Import your Bunpro export — paste in a CSV export and it bulk-loads it into the vault.

The six tools are get_review_queue, get_practice_pool, get_item, submit_grades, add_item, and import_export.

Related MCP server: bunpro-mcp

Configuration

Four environment variables. Copy .env.example to .env for local runs.

Variable	Required	What it does
`VAULT_BUCKET`	one of these two	GCS bucket holding the notes. Wins if both are set.
`VAULT_PATH`	one of these two	Local folder of notes. The local-development option.
`MCP_AUTH_TOKEN`	yes	The one secret. See below.
`MCP_PUBLIC_URL`	in production	The externally reachable base URL. Defaults to `http://localhost:$PORT`.
`PORT`	no	Injected by Cloud Run. Defaults to `8080`.
`TZ`	no	Defaults to `Asia/Singapore`.

MCP_AUTH_TOKEN does three jobs: it's the password on the OAuth login page, the key every issued token is signed with, and a bearer token accepted directly by clients that can set a header. Rotating it invalidates every token already issued — intended, but it means reconnecting afterwards.

TZ is a correctness setting, not a display one. The container runs UTC. Without it set to your timezone, an evening review lands on tomorrow's date and the whole review schedule drifts a day.

Running it locally

1. Install `uv`

curl -LsSf https://astral.sh/uv/install.sh | sh

2. Install dependencies

cd bunpro-mcp
uv sync

3. Run against a local folder

mkdir -p /tmp/test-vault
VAULT_PATH=/tmp/test-vault MCP_AUTH_TOKEN=dev uv run bunpro-mcp

Serves on http://localhost:8080. Grammar/ and Vocab/ subfolders are created on first write.

curl localhost:8080/health                                    # {"status":"ok"}
curl -s -o /dev/null -w '%{http_code}\n' localhost:8080/mcp   # 401 — auth works

Tests

uv run pytest

Poking at the tools by hand

The MCP Inspector talks to the tools directly, with no model in the loop:

VAULT_PATH=/tmp/test-vault uv run mcp dev src/bunpro_mcp/server.py

Call import_export with the contents of fixtures/sample_bunpro.csv (dry run first, then for real), then get_review_queue, get_item, and submit_grades, and confirm the queue ordering changes after grading.

To try get_practice_pool, first give it some well-known items — import the sample telling it you already know those words, or grade a few items 4 a couple of times. Then confirm it returns those mastered items, strongest-first, with weaker ones absent.

Deploying to Cloud Run

The scripted path

./deploy.sh --seed ~/Obsidian/Japanese --dry-run-seed   # check what would upload
./deploy.sh --seed ~/Obsidian/Japanese                  # seed, then deploy
./deploy.sh                                             # redeploy later

It's idempotent — safe to re-run. It enables the required APIs, creates the bucket (with versioning) and the secret if they don't exist, optionally seeds the bucket from a local vault, deploys, sets MCP_PUBLIC_URL to the service URL, scopes the service account to that one bucket, and health-checks the result. An existing secret's value is left alone.

Config via env vars, defaults shown: PROJECT (current gcloud project), REGION (asia-southeast1), VAULT_BUCKET (<project>-bunpro-vault), SERVICE (bunpro-mcp), SECRET (bunpro-mcp-token), TZ_VALUE (Asia/Singapore).

The manual equivalent

gsutil mb -l asia-southeast1 gs://$VAULT_BUCKET
gsutil versioning set on gs://$VAULT_BUCKET

# tr -d '\n' matters: openssl appends a newline, and a secret with a trailing
# newline can never be typed into the login form.
openssl rand -base64 32 | tr -d '\n' | gcloud secrets create bunpro-mcp-token --data-file=-

python scripts/seed_bucket.py ~/Obsidian/Japanese --bucket $VAULT_BUCKET

gcloud run deploy bunpro-mcp --source . --region asia-southeast1 \
  --allow-unauthenticated --max-instances=1 --memory 512Mi --timeout 300 \
  --set-env-vars VAULT_BUCKET=$VAULT_BUCKET,TZ=Asia/Singapore \
  --set-secrets MCP_AUTH_TOKEN=bunpro-mcp-token:latest

# The URL only exists after the first deploy, so this is a second step.
URL=$(gcloud run services describe bunpro-mcp --region asia-southeast1 --format='value(status.url)')
gcloud run services update bunpro-mcp --region asia-southeast1 \
  --update-env-vars "MCP_PUBLIC_URL=$URL"

Grant the runtime service account roles/storage.objectAdmin on that one bucket only, and roles/secretmanager.secretAccessor on the secret.

Two things that look wrong and aren't:

--allow-unauthenticated — Claude can't mint Google IAM tokens, so IAM can't be the gate. OAuth is. Every route except /health and /login returns 401 without a valid token.
--max-instances=1 — the container is the bucket's only writer, and keeping it to one instance keeps write conflicts to the rare deploy-overlap case rather than the normal path.

Check it came up:

curl https://<your-service-url>/health     # {"status":"ok"}

Connecting Claude

Get the token — it's the password you'll type on the login page:

gcloud secrets versions access latest --secret=bunpro-mcp-token

Claude on web or mobile

Settings → Connectors → Add custom connector:

URL: https://<your-service-url>/mcp
Leave the Advanced OAuth Client ID and Client Secret fields empty — the server registers Claude automatically.

Claude opens a login page. Paste the token, click Approve, and the six tools appear in the tools menu.

The connector authenticates by OAuth 2.1, which is the only method this dialog supports — there's no field for a fixed header outside enterprise-managed connectors. The server implements the full flow (dynamic registration, PKCE, authorization code, refresh) and issues its own tokens, so there's no third-party identity provider involved.

Claude Code, and other header-capable clients

The server also accepts the token directly as a bearer credential, so any client that lets you set a request header can skip the OAuth flow entirely:

Authorization: Bearer <token>

In Claude Code that's roughly claude mcp add --transport http bunpro https://<your-service-url>/mcp --header "Authorization: Bearer <token>" — check claude mcp add --help for the flags your version uses, as they have changed between releases.

Claude Desktop can also use the connector UI above, which is the same OAuth flow and needs no config file.

You can confirm the header path works before wiring any client to it:

curl -s -X POST https://<your-service-url>/mcp \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

That should list all six tools. The same request without the header returns 401.

Rotating the token

openssl rand -base64 32 | tr -d '\n' | gcloud secrets versions add bunpro-mcp-token --data-file=-
./deploy.sh

Cloud Run picks up the new version on the next revision. Every issued token stops working, because the signing key derives from this secret — so reconnect the web connector and update any header-based config. That's the intended behaviour: rotating the secret is how you revoke access.

Reading your notes in Obsidian

Mirror the bucket down on a timer (OnBootSec=1min, OnUnitActiveSec=2h, or an equivalent crontab pair):

gsutil -m rsync -r gs://$VAULT_BUCKET/ ~/Obsidian/Japanese/

Download only — never sync back up. The container is the bucket's only writer, which is what keeps write conflicts rare; pushing local edits up would need real conflict resolution that isn't built. The consequence, knowingly accepted: prose you edit locally in Obsidian stays local. Also don't pass -d with a destination above the vault folder, or it will delete unrelated files.

Troubleshooting

The connector won't connect, with no useful error. Almost always MCP_PUBLIC_URL not matching the URL Claude dialled — it's advertised as the OAuth issuer and clients compare it. Check it:

curl https://<your-service-url>/.well-known/oauth-authorization-server

The issuer must be your service URL. If it says http://localhost:8080, the variable was never set — run ./deploy.sh, or set it manually as shown above.

The login page rejects the correct token. Check the stored secret for a trailing newline:

gcloud secrets versions access latest --secret=bunpro-mcp-token | xxd | tail -1

If it ends 0a, it was created without tr -d '\n'. The server strips whitespace, so this should no longer bite, but a secret created before that fix and never rotated is worth checking.

Tools don't appear after connecting. Confirm the server sees the vault — /health returns 200 even when the bucket is unreachable, deliberately, so that a transient storage error doesn't take down a healthy revision. Check the logs:

gcloud run services logs read bunpro-mcp --region asia-southeast1 --limit 50

Reviews land on the wrong day. TZ isn't set. See Configuration.

Notes

Nothing is ever deleted. Items you're done with are suspended, never removed from the vault. Bucket versioning is on as a backstop.
Revocation is rotation. The server issues signed, self-contained tokens with no revocation list — /revoke is advertised for spec compliance but can't invalidate a token early. Rotating MCP_AUTH_TOKEN invalidates all of them at once.

Available Tools

6 tools

add_itemA

Add a Japanese grammar point or word the learner has just encountered. Fill in the reading, meaning, and JLPT level yourself from your own knowledge of Japanese — do not ask the learner for them unless the word is genuinely ambiguous. Put any context the learner gave you (where they met it, what confused them) into note. If the learner says they already partly know this word (e.g. "I'm Adept on this" or quotes a Bunpro SRS stage), pass that bucket as progress — one of Beginner, Adept, Seasoned, Expert, Master — so the review schedule starts from their actual familiarity instead of treating it as brand new. Leave progress unset for something they are meeting for the first time.

ParametersJSON Schema

Name	Required	Description	Default
`kind`	Yes
`note`	No
`tags`	No
`level`	No
`meaning`	No
`reading`	No
`surface`	Yes
`progress`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`item`	Yes
`created`	Yes
`already_exists`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It explains that the AI should fill in reading, meaning, JLPT from its own knowledge, and put context into note. It does not mention return values or side effects beyond adding, but the expected behavior is well communicated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single paragraph that is front-loaded with purpose and provides detailed guidance without extraneous words. Each sentence adds value, though the structure could be improved with bullet points for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (8 parameters, 2 required) and no annotations, the description is fairly complete. It covers usage scenarios, parameter guidance, and edge cases (e.g., setting progress for known items). Missing details on output schema are acceptable as output schema exists separately.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must explain parameter semantics. It adds meaning for reading, meaning, level, note, progress, and kind, covering most parameters except tags. This provides significant value beyond the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Add a Japanese grammar point or word', specifying the verb 'Add' and the resource 'Japanese grammar point or word'. It distinguishes itself from sibling tools like get_item by focusing on creation. The purpose is unambiguous and specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool: 'the learner has just encountered' a word. It gives guidelines on handling known vs new items and how to set progress. However, it does not explicitly state when not to use the tool or mention alternatives among siblings, which prevents a higher score.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_itemA

Get everything known about one Japanese grammar point or word, including the learner's own notes from their vault.

ParametersJSON Schema

Name	Required	Description	Default
`item_id`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`id`	Yes
`body`	Yes
`kind`	Yes
`level`	Yes
`lapses`	Yes
`meaning`	Yes
`reading`	Yes
`surface`	Yes
`priority`	Yes
`last_error`	Yes
`retrievability`	Yes
`days_since_review`	Yes
`days_since_first_seen`	Yes

TDQS

A3.9/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description indicates a read operation without any destructive effects, which is sufficient given no annotations. However, it could be more explicit about being non-destructive and about prerequisites like needing a valid item_id.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that front-loads the action and return content. No superfluous words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the presence of an output schema, the description adequately covers what is returned (comprehensive info including notes). It lacks details on error behavior or edge cases, but is sufficient for a simple retrieval tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter item_id is not described in the schema (0% coverage), and the description does not elaborate on how to obtain or format the ID. The agent is left to infer that item_id is a unique identifier, but no additional context is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves everything known about a single Japanese grammar point or word, including the learner's notes. It distinguishes from siblings like add_item (create) and get_practice_pool (list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used when full details on a specific item are needed, but it does not explicitly state when to use it versus alternatives or provide when-not guidance. The sibling tools have different purposes, so it is reasonably clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_practice_poolA

Get a pool of Japanese words and grammar the learner has ALREADY mastered, for active-use practice — the opposite of the review queue. Use this when the learner wants to be tested on or practice words they already know, not review what they're forgetting. Workflow: (1) ideate a concrete conversation theme or scenario (ordering at an izakaya, complaining about the weather, a job interview); (2) call this to get the mastered pool; (3) the pool is NOT pre-filtered by theme — from it, you pick the words and grammar that fit your theme, using each item's meaning; (4) propose the scenario and your chosen words to the learner and get their buy-in before starting; (5) run the practice conversation; (6) at the end, call submit_grades once for every item you practiced — grade fluent use 3 or 4, hesitation 2, and a blank or misuse 1 with a one-sentence error_note. Returns each item with its meaning and reading so you can select by theme.

ParametersJSON Schema

Name	Required	Description	Default
`kind`	No		both
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`pool`	Yes
`returned`	Yes
`generated_at`	Yes
`total_mastered`	Yes

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Describes key behaviors: returns mastered items with meaning/reading, no pre-filtering by theme. No annotations exist, so description carries full burden. Could mention ordering or size constraints, but limit parameter addresses size. Good overall.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Information-dense with essential workflow details. Slightly verbose in places (e.g., repeating contrast with review queue), but front-loaded with main purpose. Efficient overall.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers pre-use, usage, and post-use steps, and references output schema by mentioning meaning/reading. Missing parameter explanations, but otherwise complete for a tool with output schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage 0% and description does not explain the 'kind' parameter (enum of grammar/vocab/both) or 'limit'. Only workflow implies both word types, but no clarification. Fails to add meaning beyond schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it returns mastered items for active practice, contrasting with review queue. Specific verb 'Get', resource 'pool of mastered words/grammar', and purpose 'active-use practice'. Distinguishes from sibling get_review_queue.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says when to use ('when learner wants to be tested on known words, not review forgotten ones') and provides a full 6-step workflow including after-call actions like item selection and submit_grades. Also notes pool is not pre-filtered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_review_queueA

Get the Japanese items most in need of review right now, ordered by priority. Call this at the start of a review session. Returns grammar points and vocabulary with a freshness score for each, plus a note on how the learner last got it wrong.

ParametersJSON Schema

Name	Required	Description	Default
`kind`	No		both
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`queue`	Yes
`returned`	Yes
`total_items`	Yes
`generated_at`	Yes
`grammar_focus`	Yes

TDQS

A3.7/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It describes return values (grammar/vocab, freshness, mistake notes) but does not disclose mutability, auth requirements, or other side effects. Adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise, front-loaded with main action, and no unnecessary words. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and presence of output schema, description covers purpose, usage, and output format. Lacks parameter details, but overall sufficient for an agent to understand when and why to use it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, meaning no descriptions in schema. The description does not explain the 'kind' or 'limit' parameters, leaving the agent without guidance on how to use them effectively.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves Japanese items needing review, ordered by priority. It specifies the items are grammar and vocabulary with freshness and mistake notes, distinguishing it from sibling tools like get_practice_pool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly advises calling at the start of a review session, providing clear context. Does not explicitly distinguish from siblings, but the usage is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

import_exportA

Import a Bunpro CSV export into the vault. ALWAYS run with dry_run=true first and show the learner the report before running for real.

ParametersJSON Schema

Name	Required	Description	Default
`dry_run`	No
`csv_path`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`errors`	Yes
`dry_run`	Yes
`skipped`	Yes
`rows_read`	Yes
`would_create`	Yes
`would_update`	Yes

TDQS

A4.2/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses the safety-oriented dry-run step but omits details on data merging, overwrite behavior, or error handling. The existence of an output schema is noted but not elaborated.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, concise and front-loaded. The first sentence states the purpose; the second provides critical usage instruction without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With two parameters and an output schema available, the description plus schema provide adequate information for correct invocation. The workflow is clear, though error conditions or report format are not detailed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds context for parameter dry_run by stating when to set it to true and that a report is shown, but it does not explain csv_path beyond its name. Partial value added.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Import a Bunpro CSV export into the vault.' The verb 'import' and resource 'Bunpro CSV export' are specific, and the tool is distinguished from sibling tools like add_item or get_item by its import nature.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'ALWAYS run with dry_run=true first and show the learner the report before running for real.' This instructs the agent on the safe workflow and leverages the dry_run parameter.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

submit_gradesA

Record how the learner performed on items during a review. Call this at the END of a review session, once, with every item you observed. Grade 1 = could not recall or used it wrong, 2 = struggled, 3 = correct, 4 = effortless. Include a one-sentence error_note when they got it wrong, describing the specific mistake.

ParametersJSON Schema

Name	Required	Description	Default
`grades`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`summary`	Yes
`updated`	Yes
`unknown_ids`	Yes

TDQS

A4.4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses that tool should be called once at end of session, not incrementally. Explains grade meanings and error_note requirement. Lacks details on idempotency or side effects, but appropriate for a simple write tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two succinct sentences with front-loaded purpose. Every sentence adds value: purpose, timing/scope, grade definitions, error_note instruction. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given one parameter with nested structure and existence of output schema (not shown), description covers timing, grade meaning, and error_note usage. The output schema likely covers return values. Could mention idempotency or duplicate handling, but adequate for a submission tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so description must compensate. Explains that grades array covers every item observed, defines grade values (1-4), and specifies when to include error_note. Does not describe item_id format, but context is clear.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Record' and resource 'learner performance on items during a review'. Differentiates from sibling tools (add_item, get_item, etc.) which serve different purposes.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly says 'Call this at the END of a review session, once, with every item you observed', providing clear timing and scope. Does not mention alternatives but no similar siblings exist.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

6 tool updatesv0.1.0Jul 15, 2026
- First observedadd_item
- First observedget_item
- First observedget_practice_pool
- First observedget_review_queue
- First observedimport_export
- First observedsubmit_grades

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.2/5.0

Disambiguation5/5

Each tool has a clearly distinct purpose: adding items, getting specific items, obtaining practice pools, getting review queues, importing/exporting, and submitting grades. No two tools overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (e.g., add_item, get_item, get_practice_pool). The naming is predictable and uniform.

Tool Count5/5

With 6 tools, the set is well-scoped for a Japanese SRS system. It covers the essential operations without being overly large or sparse.

Completeness4/5

The tools cover core workflows: adding, retrieving, reviewing, practicing, grading, and import/export. Missing explicit update/delete tools is a minor gap, but the import/export can handle bulk changes, and the overall surface is satisfactory.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

potto-japanOAuth
app.potto
Authoritative JLPT-graded Japanese dataset (kanji, vocab, grammar, history) via MCP and REST.
Education & Learning Tools Open Data
2
MindDory Brain A
com.minddory
Free: turn your AI chats into spaced-repetition vocabulary. 13 tools, reads and writes.
Education & Learning Tools Knowledge & Memory
132
FlipnemOAuth
com.flipnem
Build and study spaced-repetition flashcards with your agent.
Education & Learning Tools Knowledge & Memory Note Taking
2
Quizlar — voice-powered AI flashcards with spaced repetitionOAuth
io.github.quizlar
Voice-led, FSRS-scheduled flashcards from YouTube, PDFs, web, or text. Auto-graded quizzes.
Education & Learning Tools Speech Processing Knowledge & Memory
2

Related MCP Servers

FlashCardMCP
Education & Learning Tools Note Taking Text-to-Speech
Moonzhang
F
license
A
quality
D
maintenance
Converts JSON/CSV Markdown content into interactive flashcard pages with multiple templates, PDF export, and voice support for language learning.
Updated 10 months ago (2025-10-25 12:11 UTC)
4
-
bunpro-mcp
Education & Learning Tools Search
PatVandyke
A
license
A
quality
C
maintenance
An unofficial MCP server for Bunpro that exposes its review queue, search, statistics, and SRS management as tools, enabling an LLM agent to read study data and add grammar points or vocabulary to reviews.
Updated 3 months ago (2026-06-21 11:42 UTC)
23
2
MIT
anki-mcp-addon
Education & Learning Tools Note Taking
luiz-santos-it
A
license
Not graded
quality
B
maintenance
Enables to interact with your Anki collection through natural language, allowing you to study, edit, and analyze flashcards without external dependencies.
Updated 2 months ago (2026-07-12 16:43 UTC)
1
MIT
japanese-learning-memory
Education & Learning Tools Knowledge & Memory
hinoyayoi
F
license
A
quality
C
maintenance
A local MCP server that helps you maintain a personal Japanese learning knowledge base, including vocabulary, confusion relations, mistakes, and spaced-repetition reviews. It provides tools and prompts for managing and reviewing your Japanese learning data without calling external LLM APIs.
Updated a month ago (2026-08-10 11:36 UTC)
6
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Muslinmin/Japanese_MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

bunpro-mcp

What you can do with it

Configuration

Running it locally

1. Install uv

2. Install dependencies

3. Run against a local folder

Tests

Poking at the tools by hand

Deploying to Cloud Run

The scripted path

The manual equivalent

Connecting Claude

Claude on web or mobile

Claude Code, and other header-capable clients

Rotating the token

Reading your notes in Obsidian

Troubleshooting

Notes

Available Tools

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Output Schema

Tool Schema Changelog

Maintenance

Resources

Looking for Admin?

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

1. Install `uv`