Captain Blue210 Anki MCP Server

🚀 Anki MCP Server

An Model Context Protocol (MCP) server designed for Claude Desktop that connects to Anki via AnkiConnect and retrieves cards with the "leech" tag.

🚀 Quick Start

This Anki MCP Server is a specialized tool designed for Claude Desktop, facilitating seamless interaction with Anki through the AnkiConnect API. It efficiently retrieves cards marked with the "leech" tag and offers comprehensive data for Claude's analysis.

✨ Features

• Connect to Anki via the AnkiConnect API.
• Retrieve cards with the "leech" tag.
• Add a review tag with a date stamp to the cards.
• Provide comprehensive card data for Claude's analysis.
• Compatible with Claude Desktop.

📦 Installation

Prerequisites

• Install and run Anki.
• Install the AnkiConnect plugin in Anki.
• Node.js and npm.

Steps

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
   

📚 Documentation

Configuration

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

cp .env.example .env

Environment Variables

Usage Instructions

1. Create a .env file

Create a .env file in the project root directory and add the above environment variables. For example:

ANKI_CONNECT_URL=http://localhost:8765
ANKI_MOCK_MODE=false

2. Start the server

Run the following command to start the server:

npm start

Functionality Description

• Retrieve Cards: Call the getLeechCards method to get all cards with the "leech" tag.
• Add Review Tag: Use the addReviewTag method to add a review tag with a date stamp to the specified card.

💻 Usage Examples

Basic Usage

const { AnkiMCP } = require('anki-mcp');

// Initialize the MCP server
const mcp = new AnkiMCP({
  connectUrl: process.env.ANKI_CONNECT_URL,
  mockMode: process.env.ANKI_MOCK_MODE === 'true'
});

// Get all leech cards
async function getLeechCards() {
  try {
    const cards = await mcp.getLeechCards();
    console.log('Retrieved leech cards:', cards);
  } catch (error) {
    console.error('Error retrieving cards:', error.message);
  }
}

// Add a review tag to a card
async function addReviewTag(cardId, customPrefix = '见直し') {
  try {
    await mcp.addReviewTag(cardId, customPrefix);
    console.log('Review tag added to card', cardId);
  } catch (error) {
    console.error('Error adding tag:', error.message);
  }
}

// Start the server
async function startServer() {
  try {
    await mcp.start();
    console.log('MCP server has started and is listening...');
  } catch (error) {
    console.error('Failed to start the server:', error.message);
  }
}

Troubleshooting

• Cannot connect to Anki: Ensure that Anki is running and the AnkiConnect plugin is installed correctly.
• No leech cards found: You don't have any cards with the "leech" tag in Anki.
• Localhost connection issues: If you can't connect using localhost, please:
  1. Find your local IP address (e.g., 192.168.x.x or 10.x.x.x).
  2. Update the .env file and set ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765.
  3. Ensure that AnkiConnect allows connections from that IP.
  4. Restart the MCP server after the modification.

Test Mode

To test without changing the actual data, use the mock mode:

1. Set ANKI_MOCK_MODE=true in the .env file or use the provided .env.test file.
2. Start the server using the following command:

   npm run start:test
   

Development Mode

To enable hot reloading during development:

npm run dev

For development in mock mode, run:

npm run dev:test

📄 License

This project is licensed under the MIT License.