Anki MCP Server

Conecta-se ao Anki via AnkiConnect para recuperar flashcards marcados como leech para uso no Claude Desktop.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor MCP do Anki

Um servidor MCP (Model Context Protocol) para o Claude Desktop que se conecta ao Anki via AnkiConnect e recupera cartões marcados como "leech" (cartões problemáticos).

Recursos

  • Conecta-se ao Anki via API do AnkiConnect
  • Recupera cartões com a tag "leech"
  • Adiciona tags de revisão com data aos cartões
  • Fornece dados abrangentes dos cartões para análise pelo Claude
  • Pode ser usado com o Claude Desktop

Pré-requisitos

  • Anki instalado e em execução
  • Complemento AnkiConnect instalado no Anki
  • Node.js e npm

Instalação

  1. Clone este repositório:

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

  2. Instale as dependências:

    npm install

  3. Compile o projeto:

    npm run build

Configuração

O servidor pode ser configurado usando variáveis de ambiente. Copie o arquivo de exemplo fornecido para criar sua própria configuração:

cp .env.example .env

Em seguida, edite o arquivo .env para personalizar suas configurações:

Variável de AmbienteDescriçãoValor Padrão
ANKI_CONNECT_URLA URL da API do Anki Connecthttp://localhost:8765
ANKI_CONNECT_VERSIONA versão da API do Anki Connect a ser usada6
ANKI_MOCK_MODEAtiva o modo simulado para testes (true/false)false

Se as variáveis de ambiente não forem definidas, o servidor usará os valores padrão.

Encontrando Seu Endereço IP Local para o AnkiConnect

Se a conexão com localhost não funcionar, você precisará usar o endereço IP local do seu computador. Configure seu arquivo .env com:

ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765

Para encontrar seu endereço IP local:

  • macOS: Abra o Terminal e execute ifconfig ou ipconfig getifaddr en0 (para WiFi)
  • Windows: Abra o Prompt de Comando e execute ipconfig
  • Linux: Abra o Terminal e execute ip addr show ou hostname -I

Procure por endereços IPv4 como 192.168.x.x ou 10.x.x.x na saída.

Configuração de Teste

Para testes, um arquivo de configuração separado .env.test é fornecido:

cp .env.example .env.test

Edite .env.test para definir valores específicos de teste:

ANKI_CONNECT_URL=http://localhost:8765
ANKI_CONNECT_VERSION=6
ANKI_MOCK_MODE=true

Para executar em modo de teste:

npm run start:test

Uso

  1. Certifique-se de que o Anki esteja em execução com o AnkiConnect instalado
  2. Execute o servidor MCP: 
    npm start

Configurando o Claude Desktop

Para usar este servidor MCP com o Claude Desktop:

  1. Abra o Claude Desktop

  2. Edite o arquivo de configuração do Claude Desktop localizado em:

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

  3. Adicione a seguinte configuração à seção mcpServers:

{
  "mcpServers": {
    "anki": {
      "command": "node",
      "args": ["path/to/anki-mcp-server/dist/index.js"]
    }
  }
}

Substitua "path/to/anki-mcp-server" pelo caminho real onde você clonou este repositório.

Uso das Ferramentas MCP

Uma vez configurado, você pode usar as seguintes ferramentas no Claude:

Exemplo de Uso

Could you analyze my Anki leech cards and suggest ways to improve my study?

O Claude usará o servidor MCP para recuperar seus cartões leech e analisá-los.

Ferramentas Disponíveis

get_leech_cards

Recupera cartões marcados como leech do Anki.

Parâmetros:

  • detailed (opcional, booleano, padrão: true): Se deve retornar dados abrangentes dos cartões ou apenas IDs
  • count (opcional, número): Número de cartões aleatórios a retornar (padrão: todos os cartões)

tag_reviewed_cards

Adiciona uma tag "reviewed" com data aos cartões especificados. Isso permite que você acompanhe quais cartões você revisou com o Claude.

Parâmetros:

  • card_ids (obrigatório, array de números): Array de IDs de cartões para marcar como revisados
  • custom_tag_prefix (opcional, string, padrão: "見直し"): Prefixo personalizado para a tag

A tag terá o formato 見直し::YYYYMMDD (ou seu prefixo personalizado, se especificado).

Exemplo de uso no Claude:

I've reviewed these cards, please tag them as reviewed: [1234567890, 1234567891]

Solução de Problemas

  • "Não foi possível conectar ao Anki" - Certifique-se de que o Anki esteja em execução e o AnkiConnect esteja instalado corretamente
  • "Nenhum cartão leech encontrado" - Você não tem nenhum cartão marcado como "leech" no Anki
  • Problemas de conexão com localhost - Se você não conseguir conectar usando localhost:
    1. Encontre seu endereço IP local conforme descrito na seção de Configuração
    2. Atualize seu arquivo .env para usar ANKI_CONNECT_URL=http://YOUR_LOCAL_IP:8765
    3. Certifique-se de que o AnkiConnect esteja configurado para permitir conexões do seu endereço IP
    4. Reinicie o servidor MCP após fazer essas alterações
  • Tag não aparecendo - Certifique-se de estar fornecendo IDs de cartões válidos para a ferramenta tag_reviewed_cards

Modo de Teste

Para testes sem afetar os dados reais do Anki, você pode usar o modo simulado:

  1. Defina ANKI_MOCK_MODE=true no seu arquivo .env ou use o arquivo .env.test fornecido
  2. Execute o servidor com npm run start:test

No modo simulado, o servidor simulará todas as operações do Anki sem realmente se conectar ao Anki. Isso é útil para testar integrações com o Claude sem arriscar alterações nos dados.

Desenvolvimento

Para executar o servidor em modo de desenvolvimento com recarregamento automático:

npm run dev

Para desenvolvimento com modo simulado ativado:

npm run dev:test

Licença

MIT