Anki MCP Server

Interaja com o software de flashcards Anki usando LLMs por meio do complemento AnkiConnect.

Documentação

Anki MCP Server

Um servidor Model Context Protocol (MCP) que permite que LLMs interajam com o software de flashcards Anki por meio do AnkiConnect.

Recursos

Ferramentas

anki_check_connection - Verifica se o AnkiConnect está acessível
anki_list_decks - Lista todos os baralhos Anki disponíveis, opcionalmente com IDs de baralhos
anki_create_deck - Cria um novo baralho Anki
anki_list_tags - Lista todas as tags atualmente usadas na coleção
anki_add_note_tags - Adiciona tags a uma ou mais notas
anki_remove_note_tags - Remove tags de uma ou mais notas
anki_create_note - Cria uma nova nota
anki_batch_create_notes - Cria várias notas de uma vez
anki_search_notes - Pesquisa notas usando a sintaxe de consulta do Anki
anki_get_note_info - Obtém informações detalhadas sobre uma nota
anki_update_note - Atualiza os campos e/ou tags de uma nota existente
anki_delete_note - Exclui uma ou várias notas
anki_list_note_types - Lista todos os tipos de nota disponíveis
anki_create_note_type - Cria um novo tipo de nota
anki_get_note_type_info - Obtém a estrutura detalhada de um tipo de nota
anki_sync - Aciona a sincronização com o AnkiWeb; requer {"confirm": true} porque uma sincronização completa pode mesclar ou sobrescrever coleções locais e remotas. Sucesso significa que o Anki aceitou a solicitação, não que o AnkiWeb recebeu os dados; uma caixa de diálogo bloqueante no Anki pode manter a sincronização na fila silenciosamente

Nomes de ferramentas legados sem prefixo, como create_note e list_decks, permanecem chamáveis para clientes existentes, mas novas integrações de agentes devem usar os nomes anki_*.

Recursos

anki://decks/all - Lista completa de baralhos disponíveis com IDs de baralhos
anki://tags/all - Lista completa de tags
anki://note-types/all - Lista de todos os tipos de nota disponíveis
anki://note-types/all-with-schemas - Informações detalhadas de estrutura para todos os tipos de nota
anki://note-types/{modelName} - Informações detalhadas de estrutura para um tipo de nota específico

Pré-requisitos

Anki instalado no seu sistema
AnkiConnect add-on instalado no Anki
Node.js 20.11 ou mais recente

Configuração

Instalar via Extensão de Desktop (.mcpb)

Este repositório suporta Extensões de Desktop da Anthropic (MCPB). A maneira mais fácil de usar este servidor no Claude Desktop é instalando o pacote .mcpb.

Gere o arquivo .mcpb localmente usando o script fornecido:

npm run mcpb

Abra Configurações do Claude Desktop → Extensões e arraste o arquivo .mcpb gerado, depois clique em Instalar.

Isso valida manifest.json e gera um arquivo .mcpb que você pode instalar como acima. Saiba mais sobre Extensões de Desktop no anúncio da Anthropic: Desktop Extensions: One-click MCP server installation for Claude Desktop.

Uso com Claude Desktop

Adicione o servidor ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

Usando Porta Personalizada do AnkiConnect

Se o seu AnkiConnect estiver rodando em uma porta diferente, você pode especificá-la usando o parâmetro --port:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Configuração para Cline

Adicione o servidor ao arquivo de configurações MCP do Cline dentro das configurações do VSCode cline_mcp_settings.json

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server"]
    }
  }
}

Usando Porta Personalizada do AnkiConnect

Para o Cline, você também pode especificar uma porta personalizada:

{
  "mcpServers": {
    "anki": {
      "command": "npx",
      "args": ["--yes", "anki-mcp-server", "--port", "8080"]
    }
  }
}

Habilidades do Agente (Claude Code)

Instale a habilidade Anki para dar ao Claude Code conhecimento integrado de todas as ferramentas e fluxos de trabalho do Anki:

npx skills add nailuoGG/anki-mcp-server@anki

Uma vez instalado, o Claude Code usará automaticamente a habilidade quando você pedir para criar flashcards, gerenciar baralhos ou importar notas em lote.

Nota: Não use a versão empacotada .mcpb como servidor MCP — ela gera metadados do Electron na saída padrão, o que quebra o protocolo MCP stdio. Use npx -y anki-mcp-server em vez disso.

Desenvolvimento

Empacotando uma Extensão de Desktop (.mcpb)

Crie um pacote de Extensão de Desktop distribuível para o Claude Desktop:

npm run mcpb

Isso construirá o projeto e gerará um arquivo .mcpb a partir do repositório atual, validando manifest.json. Teste arrastando-o para as configurações de Extensões do Claude Desktop. Referência: Desktop Extensions: One-click MCP server installation for Claude Desktop.

Publicação no Registro MCP

Este servidor é publicado automaticamente no Registro MCP quando uma nova versão é lançada. O processo de publicação inclui:

CI/CD Automatizado: GitHub Actions publica automaticamente tanto no NPM quanto no Registro MCP em lançamentos bem-sucedidos
Validação de Esquema: O arquivo server.json é validado contra o esquema MCP antes da publicação
Sincronização de Versões: As versões são mantidas em sincronia entre package.json, manifest.json e server.json
Testes Abrangentes: Testes com múltiplas versões do Node.js, linting e validação antes da publicação
Suporte a Beta: Lançamentos beta automatizados para testar novos recursos

Validação Manual

Você pode validar a configuração do servidor MCP localmente:

npm run validate-mcp

Isso baixará o esquema MCP mais recente e validará seu arquivo server.json.

Publicação Manual

Se você precisar publicar manualmente, pode usar a CLI do Publicador MCP:

# Install MCP Publisher
curl -L "https://github.com/modelcontextprotocol/registry/releases/download/v1.1.0/mcp-publisher_1.1.0_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
chmod +x mcp-publisher
sudo mv mcp-publisher /usr/local/bin/

# Login to MCP Registry
mcp-publisher login github-oidc

# Publish to MCP Registry
mcp-publisher publish

Configuração

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Testes

Execute a suíte de testes:

npm test

Isso executa testes unitários para esquemas de ferramentas MCP, resultados estruturados de ferramentas, criação de notas, fluxos de trabalho de busca/atualização/exclusão e tratamento de erros. Esses testes usam clientes AnkiConnect simulados; use o MCP Inspector com uma instância Anki em execução para verificações manuais de integração.

Avaliações MCP

Os ativos de avaliação de agentes somente leitura estão em evals/. Carregue a fixture em um perfil Anki descartável e execute as perguntas XML contra o servidor MCP para verificar se os agentes conseguem descobrir baralhos, tags, esquemas de tipos de nota, recursos e resultados estruturados de ferramentas.

Depuração

Como os servidores MCP se comunicam via stdio, recomendamos usar o MCP Inspector:

npm run inspector

Isso fornece uma interface baseada em navegador para:

Monitorar mensagens MCP
Testar invocações de ferramentas
Visualizar logs do servidor
Depurar problemas de comunicação

Exemplo de Uso

Crie um novo baralho:

Create a new Anki deck called "Programming"

Adicione um cartão básico:

Create an Anki card in the "Programming" deck with:
Front: What is a closure in JavaScript?
Back: A closure is the combination of a function and the lexical environment within which that function was declared.

Adicione um cartão de exclusão cloze:

Create a cloze card in the "Programming" deck with:
Text: In JavaScript, {{c1::const}} declares a block-scoped variable that cannot be {{c2::reassigned}}.

Exclua uma única nota:

Delete note ID 1234567890

Exclua várias notas de uma vez:

Delete note IDs 1234567890, 9876543210, and 1122334455

Adicione tags a notas:

Add tags "review" and "mcp" to note IDs 1234567890 and 9876543210

Contribuindo

Faça um fork do repositório
Crie seu branch de recurso
Execute os testes: npm test
Envie um pull request

Histórico de Estrelas

Créditos

Ícone cortesia de macOS Icons

Licença

Licença MIT - veja o arquivo LICENSE para detalhes