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

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