Anki AI MCP Server 🤖📚

Este é um repositório completo que fornece um servidor MCP (Model Context Protocol) para integrar o seu Anki Desktop com Inteligências Artificiais modernas. Ele oferece duas formas de uso:

1. Cliente Local (via TypeScript/Stdio): Ideal para editores locais como Cursor, Windsurf, Claude Desktop, etc.

2. Cliente Web (via Python/SSE + ngrok): Ideal para conectar diretamente ao site do ChatGPT (Web) no formato Sandbox (seguro).

Com este servidor, a IA ganha "superpoderes" para ler, criar, buscar, editar e analisar seu banco de estudos diretamente pelo chat, inclusive extraindo textos e mídias de documentos PDF.

🔌 1. Pré-requisitos Gerais (Para Ambos os Métodos)

Para que qualquer uma das integrações funcione, o seu computador precisa estar configurado:

A. Instalar o Anki Desktop 💻

O servidor MCP precisa se comunicar com o aplicativo instalado no seu computador.

• Baixe e instale o Anki Desktop.

• (Opcional) Crie uma conta no AnkiWeb para sincronizar seus cartões.

B. Instalar o add-on AnkiConnect 🔌

O Anki precisa de uma extensão para conseguir conversar com o nosso servidor MCP.

1. Abra o seu Anki Desktop.

2. Vá no menu superior em Ferramentas -> Complementos (Add-ons).

3. Clique em Adquirir Complementos... (Get Add-ons).

4. Insira o código do AnkiConnect: 2055492159 e clique em OK.

5. Reinicie o Anki para ativar a extensão.

Related MCP server: Anki MCP Server

🛠️ Método A: Servidor Local TypeScript (Cursor, Claude Desktop, etc.)

Este método executa o servidor localmente através do terminal (stdio). Ele tem acesso completo de leitura/escrita e suporte ao processamento de PDFs locais.

Requisitos:

• Node.js instalado (versão 18+).

• Dependências do script Python de PDF: pip install pymupdf pillow.

Configuração:

1. Abra a pasta do projeto no terminal e rode:

   npm install
   npx tsc

2. Adicione o servidor nas configurações MCP do seu editor/cliente. Exemplo de configuração para o claude_desktop_config.json:

   {
     "mcpServers": {
       "anki-server": {
         "command": "node",
         "args": [
           "C:/caminho/do/projeto/build/index.js"
         ]
       }
     }
   }

🌐 Método B: Ponte Sandbox Python (ChatGPT Web)

Este método expõe um servidor HTTP/SSE local na porta 8000 e utiliza o ngrok para criar um túnel seguro. Ele foi desenvolvido em modo Sandbox (sem acesso aos seus arquivos locais), permitindo que você conecte o ChatGPT (Web) com segurança.

Requisitos:

• Python 3.10+ instalado.

• Conta e CLI do ngrok configurada.

Como Rodar e Conectar:

1. Inicie o servidor MCP rodando o arquivo run.bat ou executando no terminal:

   pip install -r requirements.txt
   python server.py

2. Abra um terminal e inicie o túnel do ngrok:

   ngrok http 8000

   (Dica: Registre 1 domínio estático gratuito no site do ngrok e rode ngrok http --url=seu-dominio.ngrok-free.dev 8000 para manter a URL permanente).

3. Acesse o ChatGPT Web, vá em Settings -> Apps, ative o Developer Mode e clique em Add Custom Connector.

4. Configure a URL gerada pelo ngrok com /sse no final:

   • URL: https://seu-dominio.ngrok-free.dev/sse

🧰 Lista de Superpoderes Disponíveis (MCP Tools)

• list_decks / anki_get_deck_names: Lista todos os seus baralhos locais.

• create_deck / anki_create_deck: Cria um novo baralho no Anki.

• list_models: Lista os modelos de nota disponíveis no Anki (ex: Básico, Basic).

• list_model_fields: Lista os campos específicos de um modelo de nota (ex: ['Frente', 'Verso']).

• add_card / anki_add_note: Cria e adiciona um card (Frente e Verso) no baralho escolhido. Mapeia automaticamente as perguntas/respostas para os campos do modelo (ex: Frente/Verso ou Front/Back).

• add_multiple_cards: Adiciona múltiplos cards ao mesmo tempo de forma otimizada.

• search_cards / anki_find_notes: Busca e lista cards existentes com base em termos de busca (ex: "deck:Biologia DNA").

• edit_card / anki_update_note_fields: Atualiza a pergunta ou resposta de um card existente usando seu ID.

• delete_card / anki_delete_decks: Remove cards ou baralhos.

• sync_anki: Força a sincronização dos seus cartões locais com o AnkiWeb.

• store_media_file / anki_store_media_file: Salva imagens ou mídias diretamente no Anki (útil para cards com imagens criadas pelo ChatGPT).

• add_card_with_media: Cria o card e faz o upload da imagem de forma atômica em um único comando. Resolve automaticamente o mapeamento de campos (Frente/Verso ou Front/Back).

• get_capabilities: Retorna a lista completa de ferramentas e instruções recomendadas para o assistente de IA.

• anki_parse_pdf: (Apenas no Método A) Lê PDFs locais, extrai textos/mídias e anexa automaticamente as imagens extraídas na pasta de mídia do seu Anki.

💡 Exemplos de Prompts

• "Crie 5 cards de inglês no meu baralho de Vocabulário sobre palavras corporativas avançadas."

• "Procure no meu Anki por cards que mencionam 'Mitocôndria' e me traga os textos deles."

• "Altere a resposta do card de ID 1685890000000 para '42'."

• "Sincronize o meu Anki."

📄 Licença

Licença ISC. Desenvolvido para uso pessoal e integrações seguras.