AnkiChess MCP Connector

For AI assistants and the people integrating them

Overview

AnkiChess is a spaced-repetition trainer for chess openings. Its Model Context Protocol (MCP) server lets an assistant act as the user's opening coach against their real study data: it can see which lines are due, quiz them move by move with the idea behind each move, record results so the schedule adapts, manage the repertoire, and review games imported from Lichess and Chess.com.

Connection

  • Endpoint: https://ankichess.com/mcp
  • Transport: MCP Streamable HTTP. Stateless: JSON-RPC 2.0 requests over POST, JSON responses, no sessions and no server-initiated event stream (GET returns 405).
  • Protocol versions: 2025-11-25, 2025-06-18, 2025-03-26
  • Capabilities: tools and prompts.
  • CORS: enabled for all origins on /mcp. The endpoint only accepts bearer tokens, never cookies.

Authentication

Every request carries a bearer token: Authorization: Bearer <token>. There are two ways to get one, and both give access to the same tools with the same permissions.

OAuth 2.1 with PKCE

The user taps Connect in the assistant, signs in to AnkiChess, and approves the permissions on a consent screen. Nothing is copied or pasted. This is the standard MCP authorization flow, so a compliant client needs only the endpoint URL.

  • Discovery: an unauthenticated request to /mcp returns 401 with a WWW-Authenticate header whose resource_metadata points to https://ankichess.com/.well-known/oauth-protected-resource. Authorization server metadata is at https://ankichess.com/.well-known/oauth-authorization-server.
  • Clients: public clients with PKCE (S256, required). No client secret. A client identifies itself with a Client ID Metadata Document or by dynamic registration at /oauth/register. Redirect URIs are matched exactly.
  • Endpoints: /oauth/authorize, /oauth/token, /oauth/revoke.
  • Scopes: the permissions below. With no scope parameter a client is offered study and games. The user can untick any permission, and purchase is never ticked for them.
  • Tokens: access tokens last one hour. Refresh tokens last 90 days and are replaced on every use, so always store the newest one; presenting an old one disconnects the client.

API key

For assistants that take a pasted credential. Each user creates their own key in AnkiChess under Settings → AI Assistants (https://ankichess.com/app/settings/connectors) and chooses its permissions. Keys look like ack_pat_..., are shown once, and are stored only as SHA-256 hashes. A key should be collected through the assistant's secure credential input, not pasted into chat.

Either way, the user can see and revoke every connection under Settings → AI Assistants. A missing, expired or revoked token returns 401; a token without the permission a request needs returns 403.

Permissions

  • study: View and manage your repertoire, fetch due reviews, and record review results.
  • games: Read your imported games and analysis, and import new games from linked accounts.
  • purchase: Buy an AnkiChess Pro pass with a payment credential you approve.

Tools outside a token's permissions are not listed by tools/list and cannot be called. Tokens cannot reach billing, login, account or administrative functions.

Access requirements

  • An AnkiChess account. Registration is free and needs only an email address.
  • Free accounts can study 3 opening families; all tools otherwise work on the free plan. AnkiChess Pro removes the limit.
  • Game tools return data only after the user has linked Lichess or Chess.com inside AnkiChess.
  • No regional restrictions on the connector.
  • Fair use: tool calls are lightweight, but please keep automated traffic to roughly one request per second per user.

Quick start

List the tools available to a token:

curl -s https://ankichess.com/mcp \
  -H "Authorization: Bearer $ANKICHESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Fetch the line that is due next, ready to quiz:

curl -s https://ankichess.com/mcp \
  -H "Authorization: Bearer $ANKICHESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call",
       "params":{"name":"get_due_reviews","arguments":{"limit":1}}}'

Tool results carry the same data twice: as structuredContent and as JSON text in content. The server's initialize response includes instructions describing how to run a study session without revealing answers early.

Tools

Every tool declares MCP annotations. Read-only tools never change data. The only destructive tool is remove_opening.

get_account any token read-only

Who is connected, whether they have AnkiChess Pro, how many opening families they are studying versus the free limit, and what this connection is allowed to do. Call this first in a new conversation.

search_openings study read-only

Search the AnkiChess library of curated, annotated openings by name, ECO code or description. Each opening is a repertoire for ONE side ("color" is the side the learner plays). To learn an opening from the other side, look at "counteredBy" (e.g. the King's Indian Defense is a Black repertoire; its counteredBy entries are White repertoires against it). Omit the query to list everything.

get_opening study read-only

The full annotated main line of one opening: every move with the position before it (FEN), why it is played, the plan, and common mistakes. Use this to teach or quiz an opening move by move. Steps with isYourMove=true are the ones the learner must find.

list_repertoire study read-only

The opening families the user is studying with spaced-repetition progress for each: when it is next due, review count, lapses and maturity (new, learning, mature). Use this to answer "how am I doing?" and to decide what to practice.

add_opening study writes

Start studying an opening. Adds the whole opening family (the base line plus its curated variations) to the spaced-repetition queue; it becomes due immediately. Free accounts can study 3 families; if the limit is hit the result explains how to upgrade. Adding a family that is already in the repertoire is harmless.

remove_opening study destructive

Stop studying an opening family. This permanently deletes the spaced-repetition progress and move accuracy history for every variation in the family. Confirm with the user first.

get_due_reviews study read-only

The spaced-repetition cards that are due right now, most overdue first. Opening cards include the exact line to quiz (the scheduler picks which variation of the family is up). Quiz the user one move at a time on steps where isYourMove=true, telling them the opponent's replies; never reveal the answer before they try. When the line is finished, grade it with submit_review. Concept cards are flashcards on chess principles.

submit_review study writes

Record how the user did on a due card so the SM-2 scheduler can set the next review date. For opening cards pass familyId and openingId from get_due_reviews; for concept cards pass conceptId and rulesetId. Submit once per card per session, and only for cards the user actually attempted.

record_move_result study writes

Optional but valuable: record whether the user found one specific move of a line. AnkiChess uses this to start future reviews just before the moves the user keeps missing. Call it for each isYourMove step as the user answers.

list_concept_rulesets study read-only

Flashcard decks of chess principles (not move sequences), e.g. opening rules of thumb. Shows which decks the user already studies. Concept decks are free and their cards show up in get_due_reviews.

add_concept_ruleset study writes

Start studying a concept deck from list_concept_rulesets.

get_connected_accounts games read-only

Whether the user has linked Lichess and/or Chess.com to AnkiChess, with usernames and ratings. Accounts are linked by the user in the AnkiChess app, not through this connector.

import_recent_games games writes

Pull the user's latest games from a linked Lichess or Chess.com account and check each one against their repertoire. Returns how many games were imported and how many times they left book. Follow up with get_game_insights.

list_games games read-only

The user's imported games, newest first: opponent, result, opening played, and repertoireAdherence (0-1, how long they stayed in their prepared lines). Use get_game for the moves and where they deviated.

get_game games read-only

One imported game in full: PGN, moves, and every point where play left the user's repertoire, with the move they played, the book move(s), and whether it was a forgotten move, an unknown position, a sideline, or the opponent deviating.

get_game_insights games read-only

How well the user's real games follow their repertoire: adherence overall and by color, trend, kinds of deviations, which openings they keep going wrong in, and which openings they face often but have not prepared. The best starting point for "what should I study next?".

list_pro_passes purchase read-only

What an assistant can buy on the user's behalf: fixed-term AnkiChess Pro passes (unlimited opening families) with exact prices in minor units. Passes are one-time charges that never auto-renew. Payment is by Stripe Shared Payment Token (SPT) scoped to the returned stripeProfileId.

purchase_pro_pass purchase writes

Charge a Stripe Shared Payment Token for an AnkiChess Pro pass and activate it immediately. This spends the user's money: only call it after the user has approved the exact price from list_pro_passes. One token buys one pass; retrying with the same token never double-charges.

Errors

Problems the assistant can act on (unknown opening, limit reached, payment declined) come back as a normal tool result with isError: true and a machine-readable code:

{
  "isError": true,
  "structuredContent": {
    "error": "Free accounts can study 3 opening families and this account already has 3. ...",
    "code": "opening_limit_reached",
    "upgradeUrl": "https://ankichess.com/app/settings"
  }
}

Board images

Any position can be shown to the user as an image. This endpoint is public and needs no key:

https://ankichess.com/board.svg?fen=<url-encoded FEN>&orientation=white|black

Payments

With the purchase permission, an assistant can buy AnkiChess Pro for the user through Stripe agentic commerce. Passes are one-time charges that never renew: $5 for 30 days or $50 for 365 days.

  • list_pro_passes returns exact prices and the Stripe profile to pay.
  • The assistant obtains the user's approval for the exact amount and a Stripe Shared Payment Token (spt_...) for it.
  • purchase_pro_pass charges the token and activates Pro immediately. Retrying with the same token never charges twice.

AnkiChess never sees card details. The purchase permission is off by default and must be granted by the user, either when they create the key or on the OAuth consent screen.

Data and privacy

The connector exposes only the connected user's own data: their repertoire, review schedule, move accuracy, imported games and account status. It never returns other users' data, passwords, or third-party access tokens. See the Privacy Policy and Terms of Service.

Contact

Questions about the connector: [email protected]. A machine-readable summary is at /llms.txt.