# Anki MCP Server

A Model Context Protocol (MCP) server that integrates with Anki flashcard application, allowing LLM applications like Claude to interact with your Anki decks and cards.

## Features

- **Card Management**: Create, search, update, and delete flashcards
- **Deck Management**: List, create, and get statistics for decks
- **Study Sessions**: Get cards due for review and manage study sessions
- **Model Support**: Work with different note types and their fields
- **Automatic Tagging**: Cards created via MCP are automatically tagged with 'mcp-generated'

## Prerequisites

1. **Anki Desktop**: Install Anki desktop application
2. **AnkiConnect Plugin**: Install the AnkiConnect plugin in Anki
   - Go to Tools → Add-ons → Get Add-ons
   - Enter code: `2055492159`
   - Restart Anki

## Installation

1. Clone this repository:
   ```bash
   git clone <repository-url>
   cd anki-mcp
   ```

2. Install dependencies:
   ```bash
   npm install
   ```

3. Build the project:
   ```bash
   npm run build
   ```

## Usage

### Running the Server

Start the MCP server:
```bash
npm start
```

For development with auto-reload:
```bash
npm run dev
```

### Configuration with Claude Desktop

Add the server to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["/path/to/anki-mcp/dist/index.js"],
      "env": {
        "ANKI_HOST": "localhost",
        "ANKI_PORT": "8765"
      }
    }
  }
}
```

## Available Tools

### Connection Management
- **test_connection**: Test connection to AnkiConnect

### Card Management
- **create_card**: Create a new flashcard
- **search_cards**: Search for cards using Anki query syntax
- **update_card**: Update existing card fields and tags
- **delete_notes**: Delete notes and their associated cards

### Deck Management
- **list_decks**: List all available decks
- **create_deck**: Create a new deck
- **get_deck_stats**: Get statistics for a specific deck

### Study Features
- **get_cards_for_review**: Get cards that are due for review
- **get_model_names**: List available note types/models
- **get_model_fields**: Get field names for a specific model

## Example Usage in Claude

Once configured, you can use natural language commands in Claude:

- "Create a flashcard in my Spanish deck with 'hola' on the front and 'hello' on the back"
- "Search for all cards in the Spanish deck"
- "Show me cards that are due for review"
- "Create a new deck called 'French Vocabulary'"
- "What are the available note types in Anki?"

## Environment Variables

- `ANKI_HOST`: AnkiConnect host (default: localhost)
- `ANKI_PORT`: AnkiConnect port (default: 8765)

## Development

### Scripts

- `npm run build`: Build TypeScript to JavaScript
- `npm run dev`: Run in development mode with auto-reload
- `npm run watch`: Watch mode for development
- `npm test`: Run tests
- `npm run lint`: Run ESLint

### Project Structure

```
src/
├── index.ts          # Entry point
├── server.ts         # Main MCP server implementation
├── anki-client.ts    # AnkiConnect HTTP client
└── types/
    └── anki.ts       # TypeScript type definitions
```

## Troubleshooting

### Connection Issues

1. **"Cannot connect to AnkiConnect"**:
   - Ensure Anki is running
   - Verify AnkiConnect plugin is installed
   - Check that AnkiConnect is listening on port 8765

2. **"AnkiConnect error"**:
   - Check Anki error logs
   - Verify deck and model names exist
   - Ensure required fields are provided

### Configuration Issues

1. **Server not appearing in Claude**:
   - Verify the path to the built JavaScript file is correct
   - Check Claude Desktop configuration syntax
   - Restart Claude Desktop after configuration changes

2. **Permission Issues**:
   - Ensure the Node.js process has permission to execute
   - Check file paths are absolute and correct

## API Reference

The server implements the Model Context Protocol specification and provides tools for Anki integration. Each tool includes detailed input schemas and error handling.

## License

MIT License - see LICENSE file for details.

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request