htlin222/yanki-mcp-server

Yanki MCP Server ( Yet Another Anki MCP Server )

A Model Context Protocol server implementation that connects to a locally running Anki, providing card review and creation. This is a fork of scorzeth/anki-mcp-server with date-based organization features.

Available as an npm package: yanki-mcp-server

This server is designed to work with the Anki desktop app and the Anki-Connect add-on.

Make sure you have the add-on installed before using.

Resources

• anki://search/deckcurrent
  • Returns all cards from current deck
  • Equivalent of deck:current in Anki
• anki://search/isdue
  • Returns cards in review and learning waiting to be studied
  • Equivalent of is:due in Anki
• anki://search/isnew
  • Returns all unseen cards
  • Equivalent of is:new in Anki

Tools

• update_cards

  • Marks cards with given card IDs as answered and gives them an ease score between 1 (Again) and 4 (Easy)
  • Inputs:
    • answers (array): Array of objects with cardId (number) and ease (number) fields

• add_card

  • Creates a new card in a date-structured deck (format: DECK::YYYY::MM::DD)
  • Inputs:
    • front (string): Front of card
    • back (string): Back of card

• get_due_cards

  • Returns n number of cards currently due for review
  • Inputs:
    • num (number): Number of cards

• get_new_cards

  • Returns n number of cards from new
  • Inputs:
    • num (number): Number of cards

Installation & Usage

You can use this package without installation via npx:

npx yanki-mcp-server

Or install it globally:

npm install -g yanki-mcp-server
yanki-server

Development

Clone the repository and install dependencies:

git clone https://github.com/htlin222/yanki-mcp-server.git
cd yanki-mcp-server
npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Run the server directly during development:

npm run dev

Configuration

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "yanki-mcp-server": {
      "command": "npx",
      "args": ["yanki-mcp-server"],
      "env": {
        "DECK": "Default"
      }
    }
  }
}

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:

npm run inspector

The Inspector will provide a URL to access debugging tools in your browser.

Date-Based Card Organization

This server automatically organizes new cards using a date-based structure instead of traditional topic-based organization. When you create a new card, it's added to a deck with the following format:

DECK::YYYY::MM::DD

Where:

• DECK is the base deck name (default: "00_Inbox" or configured via environment variable)
• YYYY is the 4-digit year
• MM is the 2-digit month
• DD is the 2-digit day

Benefits of Date-Based Organization

1. Effortless Organization: Cards are automatically organized by creation date without manual categorization
2. Temporal Context: Review cards created during specific time periods (e.g., during a course or project)
3. Natural Spaced Repetition: Cards naturally group by when you learned concepts
4. Time-Efficient: No need to spend time deciding which category each card belongs to
5. Historical Record: See your learning journey over time

Configuration

You can customize the base deck name by setting the DECK environment variable in your MCP server configuration:

"env": {
  "DECK": "YourCustomDeckName"
}

If not specified, it defaults to "00_Inbox".

Changelog

1.0.5 (2025-05-31)

• Completely removed all console output and logging functionality
• Simplified codebase by eliminating all non-essential output
• Ensured 100% clean MCP protocol communication with no extraneous output
• Removed all filesystem operations related to logging

1.0.4 (2025-05-31)

• Fixed critical issue with logs directory path being created at filesystem root
• Improved logging system with robust error handling and fallback mechanisms
• Ensured logs are always created relative to the current working directory
• Added silent failure for logging to prevent breaking MCP protocol if logging fails

1.0.3 (2025-05-31)

• Fixed MCP communication protocol issue by redirecting all console output to log files
• Added file-based logging system that preserves all debug and status information
• Logs are stored in the logs directory with date-based filenames
• Ensured clean stdout communication for proper MCP JSON-RPC protocol compliance