Skip to main content
Glama
anki-connect-mcp
by SolarianGG
README.md
# PyAnkiConnectMCP
MCP Server for anki connect

The `anki-connect-mcp` package is an MCP server for the
[Anki-Connect API v1](https://git.sr.ht/~foosoft/anki-connect/tree/master/API_V1.md)
(JSON-RPC 2.0, `POST http://127.0.0.1:8765/api/v1`).

Each of the 95 API methods is exposed as a separate MCP tool: `decks.create` → `decks_create`,
`advanced.cards.update` → `advanced_cards_update`, and so on. Tool input schemas are generated
from the official machine-readable contract `api-v1.schema.json` (bundled with the package), so
parameters, required fields and constraints match the documentation exactly.

## Requirements

- Python 3.11+
- Anki 26.08+ with the Anki-Connect add-on (a version providing API v1) installed and enabled

## Installation

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

## Connecting a client

The server speaks MCP over stdio. The examples below use `/path/to/PyAnkiConnectMCP` for the
directory you cloned the repository into. The executable is
`.venv/bin/anki-connect-mcp` on Linux/macOS and `.venv\Scripts\anki-connect-mcp.exe` on Windows;
`python -m anki_connect_mcp` from the virtual environment works as well.

### Claude Code

```bash
claude mcp add anki -- /path/to/PyAnkiConnectMCP/.venv/bin/anki-connect-mcp
```

### Claude Desktop and other clients

Add the server to `mcpServers` in the client config:

```json
{
  "mcpServers": {
    "anki": {
      "command": "/path/to/PyAnkiConnectMCP/.venv/bin/anki-connect-mcp",
      "env": { "ANKICONNECT_API_KEY": "" }
    }
  }
}
```

### LangGraph

LangChain agents are LangGraph graphs, and LangChain loads MCP tools through `langchain.mcp`
(`langchain[mcp]>=1.4.0`). Install it in your agent's environment:

```bash
pip install "langchain[mcp]" "langchain[anthropic]"
```

Then connect the server and hand its tools to an agent:

```python
import asyncio

from langchain.agents import create_agent
from langchain.mcp import MCPAdapter

CONFIG = {
    "mcpServers": {
        "anki": {
            "command": "/path/to/PyAnkiConnectMCP/.venv/bin/anki-connect-mcp",
            # Any CLI flag from the Configuration table can be passed here.
            "args": ["--include", "decks.*,notes.*,cards.*"],
        },
    }
}


async def main():
    async with MCPAdapter(CONFIG) as adapter:
        tools = await adapter.list_tools()
        agent = create_agent("claude-sonnet-5-5", tools)
        result = await agent.ainvoke(
            {"messages": [{"role": "user", "content": "Create a deck called Vocabulary."}]}
        )
        print(result["messages"][-1].content)


asyncio.run(main())
```

Notes:

- With a single server the tool names are unchanged (`decks_create`); when the config lists
  several servers, LangChain prefixes them with the config key (`anki_decks_create`).
- `langchain.mcp` is in beta and emits a `LangChainBetaWarning` on import.
- The server process lives as long as the `async with` block; run the agent inside it.
- Pass the API key with `"args": ["--api-key", "..."]` if Anki-Connect requires one.
- `create_agent` returns a compiled LangGraph graph, so the agent can also be used as a node in
  your own `StateGraph`.
- On LangChain versions before 1.4.0, use `MultiServerMCPClient` from the
  `langchain-mcp-adapters` package with `{"anki": {"command": ..., "args": [...], "transport": "stdio"}}`
  and `await client.get_tools()` instead.

## Configuration

| Environment variable | Flag | Default | Purpose |
| --- | --- | --- | --- |
| `ANKICONNECT_URL` | `--url` | `http://127.0.0.1:8765/api/v1` | API v1 endpoint |
| `ANKICONNECT_API_KEY` | `--api-key` | — | `apiKey` from the add-on settings (sent as `Authorization: Bearer`) |
| `ANKICONNECT_TIMEOUT` | `--timeout` | `60` | HTTP timeout per request, seconds |
| `ANKI_MCP_READ_ONLY` | `--read-only` | off | Expose only read methods (plus `operations_get`) |
| `ANKI_MCP_INCLUDE` | `--include` | all | Comma-separated method patterns, e.g. `decks.*,notes.*` |
| `ANKI_MCP_EXCLUDE` | `--exclude` | — | Hide methods, e.g. `application.exit,advanced.*` |
| `ANKI_MCP_LOG_LEVEL` | — | `WARNING` | Log level (logs go to stderr) |

If your client struggles with a large number of tools, narrow the set with `--include`.

## How it works

- **Errors.** JSON-RPC errors are returned as a tool result with `isError: true` and the fields
  `code`, `type` (`notFound`, `validationFailed`, `staleSession`, …), `message` and `data`.
  HTTP rejections (401/403/405/413) and an unreachable Anki are also turned into clear errors.
- **Long-running operations.** Methods with `Completion: operation` (`collection.sync`,
  `packages.import`, `browser.open`, `api.execute`, …) return a handle. The server polls
  `operations.get` itself and returns the final result. These tools accept two extra arguments
  that are not sent to Anki:
  - `waitForCompletion` (default `true`) — `false` returns the handle immediately;
  - `timeoutSeconds` (default `300`) — when it expires, the pending operation record is
    returned; the work in Anki is not cancelled.
- **Annotations.** `readOnlyHint` is set for methods with `effect: read`, and `destructiveHint`
  for methods that delete or overwrite data. Clients use these hints to ask for confirmation.
- Write requests are never retried automatically (the documentation states explicitly that a
  request ID is not an idempotency key).

## Updating the schema

When a new API version is released, replace `src/anki_connect_mcp/api-v1.schema.json` with
`api-v1.schema.json` from the Anki-Connect repository — new methods will appear automatically.

## Tests

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest
```

TDQS

A3.6/5.0

Scored across 95 tools

Disambiguation4/5

Tools are organized by resource namespace and most actions are explicitly scoped, but with 95 operations there are many near-neighbors such as get vs getMany, validate vs validateMany, scheduling.answer vs reviewer.answer, and media.get vs media.list. The detailed descriptions usually resolve these boundaries, so an agent can distinguish them, though not effortlessly.

Naming Consistency5/5

Every tool follows a predictable resource_action convention, with the resource namespace followed by a camelCase action such as notes_create, cards_setSuspended, deckPresets_list, and advanced_cards_update. Suffix variants like getMany or deleteUnused remain systematic and consistent.

Tool Count1/5

95 tools is far beyond an appropriate MCP surface for agent selection; even for a full Anki desktop integration, many granular and long-tail operations are exposed as separate tools. This forces agents to navigate an extremely large toolset rather than a well-scoped set of workflows.

Completeness5/5

The surface comprehensively covers collection, notes, cards, decks, note types, deck presets, tags, media, scheduling, reviews, statistics, GUI/browser/editor actions, profiles, packages, operations, and advanced maintenance. There are no obvious domain lifecycle gaps.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues