Skip to main content
Glama
enesjakozh
captain-blue210

Anki MCP Server

by captain-blue210
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

Anki MCP Server

An MCP (Model Context Protocol) server for Claude Desktop that connects to Anki via AnkiConnect and retrieves leech-tagged cards.

Features

  • Connects to Anki via AnkiConnect API

  • Retrieves cards with "leech" tags

  • Adds date-stamped review tags to cards

  • Provides comprehensive card data for analysis by Claude

  • Can be used with Claude Desktop

Related MCP server: Anki MCP

Prerequisites

  • Anki installed and running

  • AnkiConnect add-on installed in Anki

  • Node.js and npm

Installation

  1. Clone this repository:

    git clone https://github.com/yourusername/anki-mcp-server.git
cd anki-mcp-server

  2. Install dependencies:

    npm install

  3. Build the project:

    npm run build

Configuration

The server can be configured using environment variables. Copy the provided example file to create your own configuration:

cp .env.example .env

Then edit the .env file to customize your settings:

Environment Variable

Description

Default Value

ANKI_CONNECT_URL

The URL of the Anki Connect API

http://localhost:8765

ANKI_CONNECT_VERSION

The version of the Anki Connect API to use

6

ANKI_MOCK_MODE

Enable mock mode for testing (true/false)

false

If the environment variables are not set, the server will use the default values.

Finding Your Local IP Address for AnkiConnect

If connecting to localhost doesn't work, you'll need to use your computer's local IP address instead. Configure your .env file with:

ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765

To find your local IP address:

  • macOS: Open Terminal and run ifconfig or ipconfig getifaddr en0 (for WiFi)

  • Windows: Open Command Prompt and run ipconfig

  • Linux: Open Terminal and run ip addr show or hostname -I

Look for IPv4 addresses like 192.168.x.x or 10.x.x.x in the output.

Test Configuration

For testing, a separate configuration file .env.test is provided:

cp .env.example .env.test

Edit .env.test to set test-specific values:

ANKI_CONNECT_URL=http://localhost:8765
ANKI_CONNECT_VERSION=6
ANKI_MOCK_MODE=true

To run in test mode:

npm run start:test

Usage

  1. Make sure Anki is running with AnkiConnect installed

  2. Run the MCP server:

    npm start

Configuring Claude Desktop

To use this MCP server with Claude Desktop:

  1. Open Claude Desktop

  2. Edit the Claude Desktop configuration file located at:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

    • Linux: ~/.config/Claude/claude_desktop_config.json

  3. Add the following configuration to the mcpServers section:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["path/to/anki-mcp-server/dist/index.js"]
    }
  }
}

Replace "path/to/anki-mcp-server" with the actual path to where you cloned this repository.

MCP Tool Usage

Once configured, you can use the following tools in Claude:

Example Usage

Could you analyze my Anki leech cards and suggest ways to improve my study?

Claude will use the MCP server to retrieve your leech cards and analyze them.

Available Tools

get_leech_cards

Retrieves cards tagged as leeches from Anki.

Parameters:

  • detailed (optional, boolean, default: true): Whether to return comprehensive card data or just IDs

  • count (optional, number): Number of random cards to return (defaults to all cards)

tag_reviewed_cards

Adds a date-stamped "reviewed" tag to specified cards. This allows you to track which cards you've reviewed with Claude.

Parameters:

  • card_ids (required, array of numbers): Array of card IDs to tag as reviewed

  • custom_tag_prefix (optional, string, default: "見直し"): Custom prefix for the tag

The tag will be in the format 見直し::YYYYMMDD (or your custom prefix if specified).

Example usage in Claude:

I've reviewed these cards, please tag them as reviewed: [1234567890, 1234567891]

Troubleshooting

  • "Could not connect to Anki" - Make sure Anki is running and AnkiConnect is properly installed

  • "No leech cards found" - You don't have any cards tagged as "leech" in Anki

  • Connection issues with localhost - If you're unable to connect using localhost:

    1. Find your local IP address as described in the Configuration section

    2. Update your .env file to use ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765

    3. Make sure AnkiConnect is configured to allow connections from your IP address

    4. Restart the MCP server after making these changes

  • Tag not appearing - Make sure you're providing valid card IDs to the tag_reviewed_cards tool

Testing Mode

For testing without affecting actual Anki data, you can use the mock mode:

  1. Set ANKI_MOCK_MODE=true in your .env file or use the provided .env.test file

  2. Run the server with npm run start:test

In mock mode, the server will simulate all Anki operations without actually connecting to Anki. This is useful for testing Claude integrations without risking data changes.

Development

To run the server in development mode with hot reloading:

npm run dev

For development with mock mode enabled:

npm run dev:test

License

MIT

Available Tools

2 tools
get_leech_cardsB

Retrieve cards tagged as leeches from Anki

ParametersJSON Schema
NameRequiredDescriptionDefault
detailedNoWhether to return detailed card information or just IDs
countNoNumber of random cards to return (defaults to all)

TDQS

B3.1/5.0
Behavior2/5

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

No annotations are provided, so the description carries full burden for behavioral disclosure. While 'Retrieve' implies a read operation, it doesn't specify whether this requires authentication, how results are returned (format, pagination), error conditions, or performance characteristics. The description is minimal and lacks behavioral context.

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, clear sentence with zero wasted words. It's appropriately sized for a simple retrieval tool and front-loads the essential information. Every word earns its place.

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

Completeness3/5

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

For a retrieval tool with 2 parameters and 100% schema coverage but no annotations or output schema, the description provides basic purpose but lacks behavioral context and usage guidance. It's minimally adequate but has clear gaps in explaining how the tool behaves and when to use it.

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 100%, so the schema already documents both parameters thoroughly. The description adds no parameter-specific information beyond what's in the schema. Baseline 3 is appropriate when the schema does the heavy lifting, though no additional semantic context is provided.

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

Purpose4/5

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

The description clearly states the action ('Retrieve') and target resource ('cards tagged as leeches from Anki'), making the purpose immediately understandable. It doesn't explicitly differentiate from its sibling tool 'tag_reviewed_cards', but the distinction is implied through the different operations (retrieval vs tagging).

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives or in what context. The description only states what the tool does, without mentioning prerequisites, timing considerations, or relationship to the sibling tool beyond their different names.

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

tag_reviewed_cardsC

Add a 'reviewed on date' tag to specified cards

ParametersJSON Schema
NameRequiredDescriptionDefault
card_idsYesArray of card IDs to tag as reviewed
custom_tag_prefixNoCustom prefix for the tag (default: '見直し')

TDQS

C2.9/5.0
Behavior2/5

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

With no annotations provided, the description carries the full burden of behavioral disclosure. It implies a mutation ('Add'), but doesn't clarify if this is destructive (e.g., overwrites existing tags), requires authentication, has side effects, or includes error handling. The description is minimal and lacks critical behavioral details for a write operation.

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, efficient sentence with zero waste. It's front-loaded with the core action and resource, making it easy to parse quickly.

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

Completeness2/5

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

Given the tool's mutation nature (adding tags), no annotations, and no output schema, the description is incomplete. It doesn't cover behavioral aspects like permissions, side effects, or return values, leaving significant gaps for an AI agent to understand how to use it correctly.

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 100%, so the schema fully documents both parameters (card_ids and custom_tag_prefix). The description adds no additional parameter semantics beyond implying the tag format ('reviewed on date'), which is already suggested by the schema's default value for custom_tag_prefix. Baseline 3 is appropriate as the schema does the heavy lifting.

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

Purpose4/5

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

The description clearly states the action ('Add') and target resource ('tag to specified cards'), with the specific tag content 'reviewed on date' mentioned. However, it doesn't differentiate from the sibling tool 'get_leech_cards' (which presumably retrieves rather than modifies cards), so it doesn't fully distinguish from alternatives.

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

Usage Guidelines2/5

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

No guidance is provided on when to use this tool versus alternatives. The description doesn't mention the sibling tool 'get_leech_cards' or any other context for selection, nor does it specify prerequisites like required permissions or system states.

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.

  1. 2 tool updates
    • First observedget_leech_cards
    • First observedtag_reviewed_cards
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have completely distinct purposes: one retrieves cards with a specific tag, while the other adds a tag to cards. There is no overlap in functionality or ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (get_leech_cards, tag_reviewed_cards) with clear actions and objects, making them predictable and easy to understand.

Tool Count2/5

With only 2 tools, the server feels thin for an Anki integration, lacking basic operations like creating cards, reviewing cards, or managing decks. This minimal set limits agent workflows significantly.

Completeness2/5

The toolset is severely incomplete for an Anki server, missing core CRUD operations for cards, decks, and reviews. Agents cannot perform essential tasks like adding new cards or scheduling reviews, leading to dead ends.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches