Anki MCP Server

anki-mcp-server

Leia isto em outros idiomas: English, 한국어

Um servidor Model Context Protocol (MCP) que conecta Claude e Anki, permitindo criar, gerenciar e enriquecer baralhos de flashcards por meio de linguagem natural — sem nunca abrir a interface do Anki.

Requisitos

• Python 3.9 ou superior
• Anki 2.1.x ou superior
• Add-on AnkiConnect
• Claude Desktop (ou qualquer cliente compatível com MCP)

Instalação

1. Configure o Anki e o AnkiConnect

1. Instale o Anki.
2. Instale o add-on AnkiConnect:
   • No Anki, vá para Tools > Add-ons > Get Add-ons
   • Digite o código 2055492159 e clique em OK
   • Reinicie o Anki
3. Verifique se funciona visitando http://localhost:8765 — você deve ver AnkiConnect v.6.

2. Instale o anki-mcp-server

git clone https://github.com/dhkim0124/anki-mcp-server.git
cd anki-mcp-server

python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

pip install -r requirements.txt

3. Configure o Claude Desktop

Edite o arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "anki-mcp": {
      "command": "python",
      "args": ["/absolute/path/to/anki_server.py"]
    }
  }
}

Uso

Com o Anki rodando em segundo plano, você pode pedir ao Claude coisas como:

• "Crie um baralho Python com estilo Code e adicione 10 cartões sobre decorators"
• "Mostre-me meus baralhos e suas estatísticas"
• "Pesquise cartões marcados com 'sql' e atualize o que fala sobre índices"
• "Crie um baralho personalizado em modo escuro com campos: Palavra, Definição, Exemplo, Áudio"
• "Envie esta imagem e anexe-a a um novo cartão no meu baralho de Biologia"
• "Sincronize minha coleção com o AnkiWeb"

O servidor conduz a conversa — ele faz perguntas de esclarecimento sobre baralho, estilo e tipo de cartão antes de criar qualquer coisa, e sempre pede confirmação antes de operações destrutivas.

Ferramentas Disponíveis

Gerenciamento de Baralhos

Ferramenta	Descrição
list_decks	Lista todos os baralhos com estatísticas (total, novos, pendentes, cartões em aprendizado)
create_deck	Cria um novo baralho (suporta baralhos aninhados com ::)
delete_deck	Exclui um baralho — requer confirmação explícita

Operações com Cartões

Ferramenta	Descrição
create_card	Cria um único cartão Basic (frente/verso)
create_card_batch	Cria vários cartões em uma única chamada
create_card_custom	Cria um cartão usando um tipo de nota personalizado, com anexos opcionais de áudio/imagem
search_cards	Pesquisa usando a sintaxe de consulta do Anki (tags, texto, filtros de baralho)
update_card	Edita campos e tags de um cartão existente
delete_cards	Exclui um ou mais cartões — requer confirmação explícita

Tipos de Nota e Estilização

Ferramenta	Descrição
create_note_type	Cria um tipo de nota personalizado com campos escolhidos, estilo CSS e modelos HTML
get_note_types	Lista todos os tipos de nota disponíveis e seus campos
update_note_type_style	Atualiza o CSS de um tipo de nota existente
update_note_type_template	Atualiza os modelos HTML de um tipo de nota existente

Mídia e Sincronização

Ferramenta	Descrição
add_media	Envia um arquivo de imagem ou áudio (base64) para a pasta de mídia do Anki
sync_anki	Sincroniza sua coleção local com o AnkiWeb

Modelos de Estilo

Quatro estilos integrados estão disponíveis por meio do parâmetro style em create_note_type:

Estilo	Chave	Melhor para
Padrão	"default"	Uso geral
Duolingo	"duolingo"	Aprendizado de idiomas, sensação gamificada
Modo Escuro	"dark"	Estudo noturno, menos cansaço visual
Code	"code"	Programação, algoritmos
Personalizado	"custom"	Controle total — você fornece o CSS

Para estilo personalizado, descreva o que deseja em linguagem natural e o Claude gera o CSS:

"Fundo azul escuro, detalhes em verde menta, animação suave de fade-in"

Todo CSS personalizado é validado para bloquear URLs javascript:, tags <script> e manipuladores de eventos inline antes de ser enviado ao Anki.

Estrutura do Projeto

anki-mcp-server/
├── anki_server.py      # MCP tool definitions and AnkiConnect client
├── config.py           # Constants: URL, API version, media limits
├── instructions.py     # LLM system instructions for conversational behavior
├── templates.py        # Built-in CSS themes, CSS validation, HTML generators
└── tests/
    ├── test_anki_server.py   # Tests for all tools (mocked AnkiConnect)
    └── test_templates.py     # Tests for template logic and CSS validation

Executando Testes

pip install pytest pytest-asyncio
pytest tests/ -v

Todos os testes simulam o AnkiConnect via httpx — nenhuma instância do Anki em execução é necessária.

Solução de Problemas

• O Anki deve estar aberto: O servidor MCP requer que o Anki esteja em execução.
• AnkiConnect não está respondendo: Visite http://localhost:8765 para confirmar que está ativo.
• Firewall do Windows: Talvez seja necessário permitir o Anki através do firewall para que o AnkiConnect funcione.
• Reinicie tudo: Se os problemas persistirem, reinicie o Anki, o Claude Desktop e verifique novamente o caminho do arquivo de configuração.

Contribuindo

Faça um fork do repositório e abra um pull request. Contribuições são bem-vindas em:

• Novos tipos de cartão ou estilos de modelo
• Suporte a idiomas adicionais
• Melhorias de interface e UX
• Documentação

Licença

Licença MIT — consulte LICENSE para detalhes.