Anki MCP

Servidor Anki MCP

Um servidor Model Context Protocol (MCP) que fornece integração perfeita com o Anki, permitindo que assistentes de IA interajam com sua coleção de flashcards. Crie, leia, atualize e gerencie cartões do Anki programaticamente por meio de uma interface padronizada.

Recursos

• 🎴 Gerenciamento de Cartões: Crie, recupere e atualize flashcards com personalização completa de campos
• 🔍 Busca Inteligente: Consulte cartões por ID, palavras-chave, tags, baralhos ou qualquer sintaxe de busca do Anki
• 📊 Integração de Revisão: Acesse cartões pendentes, novos cartões e responda cartões programaticamente
• 🎵 Suporte a Mídia: Tratamento automático de áudio e imagens (arquivos locais, URLs ou mídia existente)
• 🔄 Operações em Lote: Crie vários cartões com eficiência em uma única operação
• 🎯 Ferramentas Genéricas: Ferramentas flexíveis que funcionam com qualquer baralho, tipo de nota e configuração de campos

Pré-requisitos

1. Anki Desktop App - Deve estar em execução durante o uso do servidor MCP
2. AnkiConnect Add-on - Instale pelo Anki: Ferramentas → Complementos → Obter Complementos → Código: 2055492159

⚠️ Importante: O Anki deve estar em execução com o AnkiConnect habilitado para que este servidor MCP funcione.

Recursos

• anki://search/deckcurrent - Todos os cartões do baralho atual
• anki://search/isdue - Cartões pendentes de revisão
• anki://search/isnew - Novos cartões ainda não vistos
• Consultas personalizadas: anki://search/tag:vocabulary, anki://search/deck:Spanish, etc.

Ferramentas

• update_card - Atualizar cartões/notas (responder, atualizar campos, atualizar tags)
• add_card - Criar um novo flashcard com baralho, modelo e campos personalizados
• batch_add_card - Criar vários flashcards de uma vez
• get_due_cards - Obter lista de cartões pendentes de revisão
• get_new_cards - Obter lista de novos cartões ainda não vistos
• get_card - Recuperar informações detalhadas do cartão por ID ou consulta

Desenvolvimento

Instale as dependências:

npm install

Compile o servidor:

npm run build

Para desenvolvimento com recompilação automática:

npm run watch

Arquivos de Mídia

Como os Arquivos de Mídia São Tratados

Ao adicionar cartões com imagens ou arquivos de áudio, o servidor lida automaticamente com diferentes tipos de fontes de mídia:

1. Caminhos de Arquivo Locais: Se você fornecer um caminho absoluto para um arquivo no seu computador (por exemplo, /Users/mycomputer/Documents/images/prune.jpg), o servidor irá:

   • Ler o arquivo do seu disco
   • Convertê-lo para base64
   • Enviá-lo para a coleção de mídia do Anki usando a API storeMediaFile
   • Referenciá-lo no cartão pelo nome do arquivo

2. URLs: Se você fornecer uma URL (por exemplo, https://example.com/image.jpg), o Anki-Connect baixará o arquivo automaticamente quando o cartão for criado.

3. Mídia Existente: Se você fornecer apenas um nome de arquivo (por exemplo, prune.jpg), ele assume que o arquivo já existe na pasta de mídia do Anki.

Solução de Problemas com Imagens

Se as imagens não aparecerem corretamente no Anki:

1. Verifique o caminho do arquivo: Certifique-se de que o caminho para o seu arquivo de imagem está correto e que o arquivo existe
2. Permissões de arquivo: Garanta que o arquivo possa ser lido pelo aplicativo
3. Formatos suportados: O Anki suporta formatos de imagem comuns (JPG, PNG, GIF, SVG, WebP)
4. Tamanho do arquivo: Arquivos muito grandes podem causar problemas
5. Caracteres especiais: Evite caracteres especiais em nomes de arquivo sempre que possível

O servidor agora lida automaticamente com caminhos de arquivo locais, então você não precisa mais copiar imagens manualmente para a pasta de mídia do Anki.

Instalação e Configuração

Instalação

1. Clone ou baixe este repositório
2. Instale as dependências:

   npm install
   

3. Compile o servidor:

   npm run build
   

Configuração com o Claude Desktop

Adicione a configuração do servidor ao seu arquivo de configuração do Claude Desktop:

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

{
  "mcpServers": {
    "anki-mcp-server": {
      "command": "/absolute/path/to/anki-mcp-server/build/index.js"
    }
  }
}

💡 Dica: Substitua /absolute/path/to/anki-mcp-server pelo caminho completo real de onde você clonou este repositório.

Configuração com Outros Clientes MCP

Este servidor segue o protocolo MCP padrão e pode ser usado com qualquer cliente compatível com MCP. Configure-o como um servidor baseado em stdio apontando para build/index.js.

Verificação

Após a configuração:

1. Reinicie o Claude Desktop (ou seu cliente MCP)
2. Certifique-se de que o Anki esteja em execução com o AnkiConnect instalado
3. O servidor deve aparecer nos seus servidores MCP disponíveis
4. Teste com uma consulta simples como "Mostre-me 5 cartões pendentes do Anki"

Depuração

Como os servidores MCP se comunicam via stdio, a depuração pode ser desafiadora. Recomendamos usar o MCP Inspector, que está disponível como script de pacote:

npm run inspector

O Inspector fornecerá uma URL para acessar ferramentas de depuração no seu navegador, onde você pode:

• Testar chamadas de ferramentas interativamente
• Visualizar logs de requisição/resposta
• Depurar problemas de conexão
• Validar esquemas de ferramentas

Solução de Problemas

Servidor não aparece no Claude Desktop:

• Verifique se o caminho na configuração é absoluto (não relativo)
• Verifique se build/index.js existe (execute npm run build)
• Reinicie o Claude Desktop após alterações na configuração

Erros de "Connection refused" ou timeout:

• Certifique-se de que o Anki esteja em execução
• Verifique se o AnkiConnect está instalado (Ferramentas → Complementos)
• Verifique se as configurações do AnkiConnect permitem conexões localhost (padrão)

Cartões não estão sendo atualizados/criados:

• Feche o navegador do Anki se estiver aberto (limitação conhecida do AnkiConnect)
• Verifique se os nomes do baralho e do tipo de nota correspondem exatamente (sensível a maiúsculas/minúsculas)
• Verifique se os nomes dos campos correspondem à configuração de campos do seu tipo de nota

Contribuindo

Contribuições são bem-vindas! Seja corrigindo bugs, adicionando recursos ou melhorando a documentação, sua ajuda é apreciada.

Como Contribuir

1. Faça um fork do repositório no GitHub
2. Clone seu fork localmente:

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

3. Crie um novo branch para seu recurso ou correção de bug:

   git checkout -b feature/your-feature-name
   

4. Faça suas alterações e teste minuciosamente
5. Compile e teste suas alterações:

   npm install
   npm run build
   npm run inspector  # Test with MCP Inspector
   

6. Faça commit das suas alterações com mensagens claras e descritivas:

   git commit -m "Add: description of your changes"
   

7. Envie para seu fork:

   git push origin feature/your-feature-name
   

8. Abra um Pull Request no GitHub com uma descrição clara das suas alterações

Diretrizes de Desenvolvimento

• Escreva código TypeScript limpo e legível
• Siga o estilo e a estrutura de código existentes
• Teste suas alterações com o MCP Inspector
• Atualize a documentação se estiver adicionando novos recursos
• Mantenha os commits focados e atômicos

Reportando Problemas

Encontrou um bug ou tem uma solicitação de recurso? Abra uma issue no GitHub com:

• Um título claro e descritivo
• Passos para reproduzir (para bugs)
• Comportamento esperado vs. real
• Seu ambiente (SO, versão do Anki, versão do Node)

Perguntas?

Sinta-se à vontade para abrir uma issue para perguntas ou participar da discussão em issues existentes.

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENÇA para obter detalhes.

Agradecimentos

• Construído sobre o Model Context Protocol da Anthropic
• Usa AnkiConnect para integração com o Anki
• Desenvolvido com o pacote npm yanki-connect