Anki Leech Cards MCP server

This MCP (Model Context Protocol) server for Claude Desktop connects to Anki via AnkiConnect and retrieves leech-tagged cards. It helps you analyze problematic cards and improve your study strategy by providing comprehensive card data to Claude AI.

Prerequisites

• Anki installed and running
• AnkiConnect add-on installed in Anki
• Node.js and npm

Installation

1. Clone the 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

Copy the example environment file to create your own configuration:

cp .env.example .env

Edit the .env file with your preferred 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

Finding Your Local IP Address

If connecting via localhost doesn't work, use your computer's local IP address:

• macOS: Open Terminal and run ifconfig or ipconfig getifaddr en0
• 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 and update your .env file:

ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765

Running the Server

1. Ensure Anki is running with AnkiConnect installed
2. Start the MCP server:

   npm start
   

Configuring Claude Desktop

1. Open Claude Desktop

2. Edit the 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 this 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 your installation.

Using with Claude

Once configured, you can ask Claude to analyze your Anki leech cards:

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

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.

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 format will be 見直し::YYYYMMDD (or your custom prefix).

Troubleshooting

• "Could not connect to Anki": Ensure Anki is running with AnkiConnect installed
• "No leech cards found": You don't have any cards tagged as "leech" in Anki
• Connection issues:
  1. Use your local IP address instead of localhost
  2. Ensure AnkiConnect allows connections from your IP
  3. Restart the server after changes
• Tags not appearing: Verify you're providing valid card IDs

Testing Mode

For testing without affecting Anki data:

1. Set ANKI_MOCK_MODE=true in your .env file
2. Run the server with test configuration:

   npm run start:test
   

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

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

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect