An MCP server for Mochi Cards. It handles Mochi's API limits for you and works as a remote connector in Claude and ChatGPT.
This is a fork of shunkus/mochi-mcp-server. The fork replaces the Vercel/Next.js transport with a standalone Node server and adds:
- A single request queue. Mochi's API allows one
concurrent request per account and answers bursts with
429. All MCP sessions and batch jobs share one queue that sends one request at a time with a minimum gap between requests. On429the gap doubles and the request is retried, honouringRetry-After; the gap then shrinks gradually as requests succeed. Interactive calls go ahead of queued batch work. - Batch tools that run as background jobs. Mochi has no bulk endpoints.
create_cards,update_cards,delete_cardsandget_cardsaccept up to 500 items (200 forget_cards) and run them through the queue. Each one waits up towait_seconds, then returns either the results or ajob_idto poll withget_job. If an identical write batch is resubmitted within 15 minutes, the server returns the existing job instead of writing the items again. - Search. Mochi's API cannot search, so
search_cardsloads the requested decks once (100 cards per queued request), keeps them in memory and filters locally by text, field, tag or template. You can look up many terms in one call. The cache assumes cards change only through this server: its own creates, updates, moves and deletes update the index immediately, and loaded decks are kept for a week (MOCHI_SEARCH_CACHE_TTL_HOURS). Mochi offers no change feed, so edits made in the Mochi app are not detected. After such edits, passrefresh: true(reload) orverify: true(re-fetch each hit live). A restart or redeploy starts with an empty index. - Safe partial updates. When only some template fields change, the server reads the live card first and merges, so other fields are never dropped.
- Fewer requests. Deck and template lists are cached for five minutes; changes
made through this server refresh the cache.
list_cardscan follow pagination at 100 cards per page. - Safe retries.
429is always retried, because Mochi did not process the request. Timeouts, network errors and5xxresponses are retried only for idempotent calls (reads, updates and deletes), never for card or deck creation. - Streamable HTTP with OAuth 2.1, which Claude.ai and ChatGPT connectors need, plus a static bearer token for clients that can send headers.
| Area | Tools |
|---|---|
| Cards | search_cards, list_cards, get_card, create_card, update_card, delete_card, add_attachment, delete_attachment, get_due_cards |
| Batch jobs | create_cards, update_cards, delete_cards (moves to trash by default), get_cards, get_job, list_jobs, cancel_job |
| Decks | list_decks, get_deck, create_deck, update_deck, delete_deck |
| Templates | list_templates, get_template, create_template |
| Diagnostics | queue_status |
Each tool has MCP annotations (read-only, destructive, idempotent), so clients can ask
before destructive calls. add_attachment downloads only from public https URLs,
following at most three redirects, and accepts files up to 10 MiB.
| Variable | Default | Purpose |
|---|---|---|
MOCHI_API_KEY |
required | API key from Mochi → Account settings → API |
MCP_PUBLIC_URL |
required (HTTP) | Public origin, e.g. https://mochi.example.com; the endpoint is <origin>/mcp |
| < 8C24 code>MCP_AUTH_SECRET | required (HTTP) | Owner secret of at least 32 characters, e.g. openssl rand -hex 32 |
MCP_AUTH_DISABLED |
false |
true disables auth; use it only on a trusted local network |
OAUTH_REDIRECT_ALLOWLIST |
Claude, ChatGPT and loopback hosts | Comma-separated redirect hosts that OAuth clients may register; * allows any host |
OAUTH_ACCESS_TOKEN_TTL_SECONDS |
3600 |
Access token lifetime |
OAUTH_REFRESH_TOKEN_TTL_SECONDS |
2592000 |
Refresh token lifetime (30 days) |
MOCHI_MIN_INTERVAL_MS |
300 |
Minimum gap between Mochi requests |
MOCHI_MAX_INTERVAL_MS |
30000 |
Maximum adaptive gap after 429 |
MOCHI_MAX_RETRIES |
6 |
Retries per request |
MOCHI_REQUEST_TIMEOUT_MS |
30000 |
Per-request timeout |
MOCHI_MAX_PENDING |
500 |
Maximum number of queued requests |
MOCHI_SEARCH_CACHE_TTL_HOURS |
168 |
How long search_cards keeps loaded decks before reloading (one week; 0 reloads on every search) |
PORT |
8000 |
Listening port |
TRUST_PROXY_HOPS |
1 |
Reverse proxies in front of the server, used for client IPs in rate limiting |
Run one replica per Mochi account. Each process has its own queue, so a second replica would break Mochi's one-request-at-a-time limit. Batch jobs live in memory: they last 24 hours and are lost when the process restarts.
The server is its own single-user OAuth authorization server, with no database:
- A client discovers it through
/.well-known/oauth-protected-resource/mcpand/.well-known/oauth-authorization-server, then registers dynamically. - You are sent to an approval page and enter
MCP_AUTH_SECRET. A password manager can fill it in: save it as a login for your server's URL with usernameowner. - The client receives a one-hour access token and a refresh token, both protected with PKCE.
Clients, authorization codes and tokens are HMAC-signed and contain everything needed
to check them, so they survive restarts. Rotating MCP_AUTH_SECRET revokes every token
and client registration. Failed approval attempts are rate-limited, and only allowlisted
redirect hosts can register. The page shows the redirect host before you approve.
Any client that can send headers can also use Authorization: Bearer <MCP_AUTH_SECRET>.
- Claude.ai / Claude Desktop: Settings → Connectors → Add custom connector, URL
https://<host>/mcp. Leave the OAuth client fields empty. - ChatGPT: Settings → Apps & Connectors → Advanced → enable developer mode, then
create a connector with URL
https://<host>/mcpand authentication OAuth. - Claude Code:
claude mcp add --transport http mochi https://<host>/mcp --header "Authorization: Bearer $MOCHI_MCP_SECRET", or omit the header and complete OAuth with/mcp. - Local stdio:
MOCHI_API_KEY=… node dist/src/stdio.js, without HTTP or auth.
npm ci
npm test # build + unit and end-to-end tests (fake Mochi API, full OAuth flow)
npm run typecheck
MOCHI_API_KEY=… MCP_PUBLIC_URL=http://localhost:8000 MCP_AUTH_DISABLED=true npm startscripts/link-kanji.ts replaces the kanji in a vocab field with links to the matching
kanji cards ([[危|<card id>]]). It uses the same request queue as the server, so run it
while nothing else is writing heavily. Field and template IDs default to the author's
templates; override them with --field, --vocab-template and --kanji-template.
npm run build
node dist/scripts/link-kanji.js link --deck <id> --dry-run # preview, writes a JSON backup
node dist/scripts/link-kanji.js clone --deck <id> --limit 50 # archived copy for a test
node dist/scripts/link-kanji.js link --deck <id> [--limit N] # update; re-run to resume
node dist/scripts/link-kanji.js restore --log link-kanji-runs/link-….jsonlEach write takes about 0.7 seconds. Copies made by clone don't include attachments
(audio, images), because the API can't copy them.
Every push to main that changes more than docs or Dependabot config publishes a release.
A daily run catches merges made by GitHub's auto-merge, which don't trigger push workflows.
Each release:
- runs typecheck and tests;
- creates the next patch version from the latest
vX.Y.Ztag (manual runs of Release can bump the minor or major version instead); - publishes
ghcr.io/alexw00/mochi-mcp:X.Y.ZplusX.Y,Xandlatestforlinux/amd64andlinux/arm64, with provenance and an SBOM; - smoke-tests the published image, then creates the GitHub release. The release
notes contain the
X.Y.Z@sha256:…reference to pin in deployments.
Versions come from git tags; package.json keeps 0.0.0-development.
Dependabot opens weekly PRs for npm, the Docker base image and GitHub Actions.
Minor and patch updates are queued for auto-merge. Branch protection on main
requires the CI checks to pass first:
workflows: actionlinttest: typecheck and testsimage: Docker build, container smoke test, auth-required startup check
PRs that fail a check stay open. Major updates always need manual review.
ISC. See LICENSE.