MCP server

Connect Claude, Cursor, VS Code or any other MCP client to your Anki collection. The agent can then search your notes, add flashcards, organise decks and tags, and run a review session, with the same rules as the REST API. Every SDK function is a tool.

Connect#

The server is at https://ankinize.com/mcp. Most clients only need that address: they open a browser window, you sign in to Ankinize and approve, and the agent is connected. Nothing is copied or pasted.

claude mcp add --transport http ankinize https://ankinize.com/mcp
# then, inside Claude Code, run /mcp and choose "Authenticate"

Then ask in plain language: "Make ten cards from this article in my Languages deck", or "What is due today?". The agent starts by reading your decks and note types, so it uses the right fields.

Connect ChatGPT#

ChatGPT on the web takes a custom MCP server in a few clicks. It signs in with OAuth, so there is no key to copy.

Open chatgpt.com/plugins (Plugins in the sidebar), choose Add, then Add custom MCP server.
Name: Ankinize. The description is optional.
Connection: leave Server URL selected and paste https://ankinize.com/mcp.
Authentication: leave OAuth. Skip Advanced OAuth settings: ChatGPT finds the sign-in details and registers itself.
Read the risk warning, tick I understand and want to continue, then choose Create as a plugin.
Sign in to Ankinize if asked and approve on the consent screen. Untick write there for read-only access.
Start a new chat, type @ and pick Ankinize, then ask, for example "What is due today?".

Your plan or workspace may limit custom MCP servers; if Add custom MCP server is missing, ask your workspace admin. If you run Ankinize yourself and the server is not reachable from the internet, choose Tunnel instead of Server URL (see OpenAI's Secure MCP Tunnel guide). After the server's tools change, open the plugin and choose Refresh.

MCP clients register themselves with Ankinize the first time, so there is nothing to set up in the dashboard. The approval screen shows the name the client gave itself, where it will send you back to, and what it asks for. Approve only a connection you started.

Read and write is asked for by default. Untick write to give read-only access: the agent can look at your collection but the tools that change it are not even offered to it.
The connection works only with this server. It cannot call the REST API and it cannot sync: the sync scope is never offered.
You can disconnect an app at any time under API keys > Connected apps. It stops working at once and has to ask you again to come back.
Access is renewed automatically while the client stays connected. Each call in the activity log is labelled MCP · name of the client.

Using an API key instead#

For a script or a server with no browser, send an API key as a Bearer token. It is the same key the REST API takes, with the same scopes: read for looking, write for changing. A key that only has sync is refused.

claude mcp add --transport http ankinize https://ankinize.com/mcp \
  --header "Authorization: Bearer $ANKINIZE_API_KEY"

What the agent can do#

One tool per SDK function, named in snake_case: listNotes is list_notes. A tool takes the same arguments as the function and returns the same answer as JSON. The API reference describes each one. A read-only connection is offered only the tools without Changes data.

Start here#

Tool	What it does	Changes data
`describe_collection`	Decks, note types and the field keys to use when writing notes. The agent calls this first.

Decks#

Tool	What it does	Changes data
`list_decks`	List decks, optionally by name.
`get_deck`	One deck, with its card counts.
`create_deck`	Create a deck (Parent::Child nests).	Yes
`rename_deck`	Rename or move a deck.	Yes
`delete_deck`	Delete a deck and its cards.	Yes

Notes#

Tool	What it does	Changes data
`list_notes`	Search notes with Anki search syntax.
`get_note`	One note with its fields, tags and cards.
`create_note`	Add one note.	Yes
`update_note`	Change a note's fields, tags or deck.	Yes
`delete_note`	Delete a note and its cards.	Yes
`create_notes`	Add many notes; split into calls of at most 200.	Yes
`update_notes`	Change many notes at once.	Yes
`delete_notes`	Delete many notes at once.	Yes

Note types#

Tool	What it does	Changes data
`list_note_types`	List note types with their fields and templates.
`get_note_type`	One note type in full.
`create_note_type`	Add a note type.	Yes
`update_note_type`	Change fields, templates or styling. Removing a field or template forces a Full Sync on every device.	Yes
`delete_note_type`	Delete a note type and its notes.	Yes

Cards and review#

Tool	What it does	Changes data
`list_cards`	Search cards (due, suspended, new, by deck...).
`get_card`	One card with its scheduling state.
`render_card`	The question and answer a card shows.
`get_card_scheduling`	What each of the four answer buttons would do.
`get_study_queue`	What Anki would show next.
`answer_card`	Record an answer. The agent should only do this when you really answered.	Yes
`update_card`	Move, flag, suspend or bury a card.	Yes
`delete_card`	Delete a card.	Yes
`update_cards`	Change many cards at once.	Yes
`delete_cards`	Delete many cards at once.	Yes

Tags#

Tool	What it does	Changes data
`list_tags`	List tags with their note counts.
`get_tag`	One tag.
`create_tag`	Add a tag.	Yes
`rename_tag`	Rename a tag everywhere.	Yes
`delete_tag`	Remove a tag from every note.	Yes
`create_tags`	Add many tags.	Yes
`update_tags`	Rename many tags.	Yes
`delete_tags`	Remove many tags.	Yes

Statistics#

Tool	What it does	Changes data
`get_stats`	Review counts, retention, intervals and forecasts, for a search.

Media#

Tool	What it does	Changes data
`list_media`	List the collection's media files.
`get_media`	Fetch a file (images are shown to the model; up to 2 MiB).
`put_media`	Store a file for use in a note (up to 3 MiB).	Yes
`delete_media`	Delete a file.	Yes

The agent is also given a short guide it can read (ankinize://guide, ankinize://guide/search) and three prompts your client may show as commands: make_cards, quiz_me and tidy_up.

What is not a tool#

The SDK also has helpers that only make sense inside a program: pipe, flow, iter, indexBy, groupBy, nest, the paging streams and the q search builders. An agent does not need them. A search is the string in q (for example deck:Languages is:due), and a list continues with its cursor.

Safety and limits#

Concern	What happens
Deleting	Delete tools are marked as destructive, so clients ask you before running them. The server's instructions also tell the agent to ask first.
Changing a note type	Removing a field or template forces a Full Sync on every device. The call is refused until the agent sends `acceptFullSync: true`, and the account allows it.
Retries	Writes take an `idempotencyKey`: the same key does the work once.
Rate limits	The REST API's limits apply, per account. A refused call returns `rate_limited` and says how many seconds to wait.
Big answers	An answer over 150,000 characters is refused with advice to narrow the search. Media over 2 MiB is not returned and over 3 MiB is not stored through MCP; use the REST API for those.
Failures	A failed call comes back as an error the agent can read: `code`, `message` and, where it helps, a `hint`.

When it does not connect#

You see	Meaning
`401 unauthorized`	No credential, or an expired one. The `WWW-Authenticate` header points the client to the sign-in; clients that support it start it themselves. With an API key, check it is sent as `Authorization: Bearer ank_…`.
`403 forbidden`	The account is suspended or its email is not verified, or the key only has the sync scope.
`insufficient_scope`	A write was tried on a read-only connection. Connect again and leave write ticked.
401, not an access token for this server	The client signed in without naming the resource (RFC 8707), which the MCP specification requires. Update the client, or use an API key.
ChatGPT cannot connect	Check that the URL ends in `/mcp` and opens from the internet over HTTPS (a server on your own machine does not; use Tunnel), and that Authentication is OAuth. Then try Refresh on the plugin.
Cannot register	Registration only takes public clients (no secret) that use the authorization code flow with PKCE. A client that needs a secret should use an API key.

Look at it in the MCP Inspector

npx @modelcontextprotocol/inspector
# Transport: Streamable HTTP   URL: https://ankinize.com/mcp

Connect#

Connect ChatGPT#

What you approve#

Using an API key instead#

What the agent can do#

Start here#

Decks#

Notes#

Note types#

Cards and review#

Tags#

Statistics#

Media#

What is not a tool#

Safety and limits#

When it does not connect#