Anki MCP

oficial

Um servidor MCP que permite que assistentes de IA interajam com o Anki, o aplicativo de flashcards de repetição espaçada.

GitHub

372

O que você pode fazer com Anki MCP?

Revisar cartões pendentes em um baralho específico — peça ao assistente para buscar e apresentar seus cartões pendentes usando get_due_cards e present_card, depois registre suas avaliações com rate_card.
Criar flashcards em lote a partir de uma lista — forneça um conjunto de termos e definições e peça ao assistente para criar até 100 notas de uma vez via addNotes.
Pesquisar e atualizar notas existentes — encontre notas com findNotes usando a sintaxe de consulta do Anki, inspecione-as com notesInfo e modifique campos com updateNoteFields.
Gerenciar tipos de nota e estilização — crie um novo tipo de nota com createModel, ajuste seu CSS com updateModelStyling ou modifique seus modelos de cartão com updateModelTemplates.
Importar arquivos de mídia para sua coleção — faça upload de um arquivo de imagem ou áudio de um caminho local ou URL usando storeMediaFile e faça referência a ele em um campo de nota.

Documentação

Servidor Anki MCP

Integre perfeitamente o Anki com assistentes de IA através do Protocolo de Contexto de Modelo

Beta - Este projeto está em desenvolvimento ativo. APIs e funcionalidades podem mudar.

Um servidor do Protocolo de Contexto de Modelo (MCP) que permite que assistentes de IA interajam com o Anki, o aplicativo de flashcards com repetição espaçada.

Transforme sua experiência com o Anki com interação em linguagem natural — como ter um tutor particular. O assistente de IA não apenas apresenta perguntas e respostas; ele pode explicar conceitos, tornar o processo de aprendizado mais envolvente e humano, fornecer contexto e se adaptar ao seu estilo de aprendizado. Ele pode criar e editar notas rapidamente, transformando suas sessões de estudo em conversas dinâmicas. Mais funcionalidades em breve!

Exemplos e Tutoriais

Para guias abrangentes, exemplos do mundo real e tutoriais passo a passo sobre como usar este servidor MCP com o Claude Desktop, visite:

ankimcp.ai - Documentação completa com exemplos práticos e casos de uso

Veja docs/ para documentação suplementar, incluindo o guia de configuração do revisor e o baralho Anki de exemplo.

Exemplos de Casos de Uso

Três prompts representativos mostrando os fluxos de ferramentas que este servidor possibilita:

"Ajude-me a revisar meu baralho de espanhol." — O assistente sincroniza com o AnkiWeb (sync), busca cartões pendentes (get_due_cards com filtro de baralho), apresenta cada cartão (present_card) e registra sua avaliação (rate_card). Conversa de estudo natural com explicações personalizadas para você.
"Crie 10 cartões de vocabulário em árabe com estilo RTL." — O assistente lista os tipos de nota (modelNames), cria um modelo RTL personalizado se necessário (createModel + updateModelStyling para CSS da direita para a esquerda) e, em seguida, cria os cartões em lote (addNotes).
"Importe esta imagem da minha pasta Downloads para a frente da nota selecionada." — O assistente envia o arquivo local (storeMediaFile com um caminho de arquivo), lê a nota atualmente selecionada no navegador (guiSelectedNotes + notesInfo) e atualiza o campo frontal com uma tag <img> (updateNoteFields).

Ferramentas Disponíveis

O servidor expõe 42 ferramentas MCP — 31 ferramentas essenciais para operações diárias do Anki e 11 ferramentas de GUI que controlam a interface de desktop do Anki para fluxos de trabalho de edição/criação de notas.

Ferramentas Essenciais

Revisão e Estudo

sync - Sincronizar com o AnkiWeb para obter os dados mais recentes e enviar alterações
get_due_cards - Obter cartões que estão pendentes para revisão, opcionalmente filtrados por baralho
get_cards - Obter cartões com filtragem flexível por estado (pendente, novo, aprendendo, suspenso, enterrado) e baralho
present_card - Mostrar um cartão para revisão com seu lado da pergunta/frente
rate_card - Avaliar o desempenho do cartão (Novamente, Difícil, Bom, Fácil) e agendar a próxima revisão

Gerenciamento de Baralhos

listDecks - Listar todos os baralhos, opcionalmente com estatísticas de contagem de cartões por baralho
deckStats - Obter estatísticas abrangentes para um único baralho (contagens, distribuições de facilidade/intervalo)
createDeck - Criar um novo baralho vazio (suporta Parent::Child, máx. 2 níveis)
changeDeck - Mover cartões para um baralho diferente (criado se não existir)

Gerenciamento de Notas

addNote - Criar uma única nota com campos e tags especificados
addNotes - Criar em lote até 100 notas compartilhando um baralho e modelo (sucesso parcial suportado)
findNotes - Pesquisar notas usando a sintaxe de consulta do Anki (deck:, tag:, is:due, etc.)
notesInfo - Obter informações detalhadas sobre notas (campos, tags, estilo CSS)
updateNoteFields - Atualizar campos de notas existentes (ciente de CSS, suporta conteúdo HTML)
deleteNotes - Excluir notas e todos os cartões associados (destrutivo, requer confirmação)

Gerenciamento de Tags

getTags - Obter todas as tags na coleção (use primeiro para evitar duplicação)
addTags - Adicionar tags separadas por espaço às notas especificadas
removeTags - Remover tags separadas por espaço das notas especificadas
replaceTags - Renomear uma tag em todas as notas especificadas
clearUnusedTags - Remover tags órfãs não usadas por nenhuma nota (destrutivo)

Gerenciamento de Mídia

getMediaFilesNames - Listar arquivos de mídia em collection.media, opcionalmente filtrados por padrão
retrieveMediaFile - Baixar um arquivo de mídia como conteúdo base64
storeMediaFile - Enviar mídia a partir de dados base64, um caminho de arquivo absoluto ou uma URL
deleteMediaFile - Remover um arquivo de mídia de collection.media (destrutivo)

💡 Melhor Prática para Imagens:

✅ Use caminhos de arquivo (ex., /Users/you/image.png) - Rápido e eficiente
✅ Use URLs (ex., https://example.com/image.jpg) - Download direto
❌ Evite base64 - Extremamente lento e ineficiente em tokens

Basta dizer ao Claude onde a imagem está, e ele cuidará do upload automaticamente usando o método mais eficiente.

Gerenciamento de Modelos/Templates

modelNames - Listar todos os tipos de nota/modelos disponíveis
modelFieldNames - Obter nomes de campos para um tipo de nota específico
modelStyling - Obter informações de estilo CSS para um tipo de nota
modelTemplates - Obter os templates de cartão (HTML da Frente e Verso) para um tipo de nota
createModel - Criar um novo tipo de nota com campos personalizados, templates de cartão e CSS (ex., modelos RTL)
updateModelStyling - Atualizar o estilo CSS para um tipo de nota existente (aplica-se a todos os seus cartões)
updateModelTemplates - Atualizar os templates de cartão (HTML da Frente e Verso) para um tipo de nota existente (aplica-se a todos os seus cartões)
addModelField - Adicionar um novo campo a um tipo de nota existente (anexado no final ou inserido em uma posição específica)
removeModelField - Remover um campo de um tipo de nota existente (exclui seu conteúdo de todas as notas; requer confirmação explícita)
renameModelField - Renomear um campo em um tipo de nota existente (templates de cartão que referenciam o nome antigo devem ser atualizados separadamente)
repositionModelField - Alterar a posição de um campo dentro de um tipo de nota existente

Estatísticas

collection_stats - Estatísticas agregadas em todos os baralhos com detalhamento por baralho
review_stats - Análise do histórico de revisão (padrões temporais, métricas de retenção, sequências de estudo)

Ferramentas de GUI

Ferramentas que controlam a interface de desktop do Anki. Destinadas a fluxos de trabalho de edição/criação de notas e gerenciamento de baralhos, não para sessões de revisão.

guiBrowse - Abrir o Navegador de Cartões e pesquisar cartões
guiSelectCard - Selecionar um cartão específico no Navegador de Cartões
guiSelectedNotes - Obter IDs das notas atualmente selecionadas no Navegador de Cartões
guiAddCards - Abrir o diálogo Adicionar Cartões com detalhes de nota predefinidos
guiEditNote - Abrir o editor de notas para uma nota específica
guiDeckOverview - Abrir o diálogo de Visão Geral do Baralho para um baralho específico
guiDeckBrowser - Abrir o diálogo do Navegador de Baralhos
guiCurrentCard - Obter informações sobre o cartão atual no modo de revisão
guiShowQuestion - Mostrar o lado da pergunta do cartão atual
guiShowAnswer - Mostrar o lado da resposta do cartão atual
guiUndo - Desfazer a última ação no Anki

Pré-requisitos

Anki com o plugin AnkiConnect instalado
Node.js 22.12.0+

Instalação

Existem algumas maneiras de obter o servidor em sua máquina. Uma vez instalado, vá para Conectando um Cliente de IA para conectá-lo ao seu assistente de IA — local ou remotamente.

npm (global ou npx)

A forma de uso geral para instalar o servidor, adequada para qualquer cliente MCP que o inicie diretamente.

Instale-o globalmente para clientes que executam o comando ankimcp:

npm install -g @ankimcp/anki-mcp-server

Ou execute-o sob demanda sem necessidade de instalação:

npx @ankimcp/anki-mcp-server

Pacote MCPB (Recomendado para Claude Desktop)

A maneira mais fácil de instalar este servidor MCP para o Claude Desktop:

Baixe o pacote .mcpb mais recente da página de Releases
No Claude Desktop, instale a extensão:
- Método 1: Vá para Configurações → Extensões e arraste e solte o arquivo .mcpb
- Método 2: Vá para Configurações → Desenvolvedor → Extensões → Instalar Extensão e selecione o arquivo .mcpb
Configure a URL do AnkiConnect se necessário (o padrão é http://localhost:8765)
Reinicie o Claude Desktop

É isso! O pacote inclui tudo o que é necessário para executar o servidor localmente.

Para revisores do Diretório MCP da Anthropic: um passo a passo do zero à integração com um baralho de exemplo pré-preenchido está em docs/reviewer-setup.md.

Instalar a partir do Código Fonte (para desenvolvimento)

Para desenvolvimento ou uso avançado:

npm install
npm run build

Conectando um Cliente de IA

Existem duas maneiras de um assistente de IA alcançar este servidor, dependendo de onde o assistente é executado:

Local — o servidor é executado na mesma máquina que o cliente de IA (Claude Desktop, Cursor, Cline, Zed ou uma sessão de navegador local). Use STDIO para clientes MCP de desktop, HTTP para ferramentas locais baseadas na web.
Remoto — uma IA hospedada/remota (ex., ChatGPT ou Claude.ai na nuvem) precisa alcançar o Anki em execução na sua máquina local. Use o Túnel gerenciado (✅ recomendado — autenticado) ou, como uma alternativa mais leve e não autenticada, ngrok.

Local

O servidor é executado no mesmo computador que seu cliente de IA e se comunica com o AnkiConnect em localhost.

STDIO (integração local primária)

STDIO é o transporte padrão para clientes MCP de desktop locais — Claude Desktop, Cursor IDE, Cline, Zed Editor e outros. O cliente inicia o servidor como um subprocesso e se comunica através de entrada/saída padrão.

Clientes Suportados:

Claude Desktop
Cursor IDE - Editor de código com IA
Cline - Extensão do VS Code para assistência de IA
Zed Editor - Editor de código rápido e moderno
Outros clientes MCP que suportam transporte STDIO

Para o Claude Desktop, o pacote MCPB é o caminho mais fácil. Para outros clientes, configure o pacote npm com a flag --stdio.

Configuração - Escolha um método:

Método 1: Usando npx (recomendado - sem necessidade de instalação)

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Método 2: Usando instalação global

Primeiro, instale globalmente:

npm install -g @ankimcp/anki-mcp-server

Depois configure:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "ankimcp",
      "args": ["--stdio"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Locais dos arquivos de configuração:

Cursor IDE: ~/.cursor/mcp.json (macOS/Linux) ou %USERPROFILE%\.cursor\mcp.json (Windows)
Cline: Acessível via interface de configurações no VS Code
Zed Editor: Instale como extensão MCP através do marketplace de extensões

Para recursos específicos do cliente e solução de problemas, consulte a documentação do seu cliente MCP. Veja também Conectar ao Claude Desktop para uma configuração que aponta diretamente para um dist/main-stdio.js compilado.

HTTP (IA local baseada na web)

O modo HTTP executa o servidor como um servidor web local que utiliza o protocolo MCP Streamable HTTP. É o transporte com o qual uma ferramenta de IA baseada na web se comunica quando apontada para sua máquina, e também é o que as opções Remotas expõem para o mundo exterior. Por si só, o modo HTTP se vincula apenas a localhost.

Vinculando além do localhost? Se você passar --host 0.0.0.0 (ou executar atrás de um proxy reverso/domínio público), o servidor só aceita cabeçalhos Host de loopback por padrão para proteção contra rebinding de DNS — defina ALLOWED_HOSTS para o(s) nome(s) de host que os clientes usam. Veja Configuração do Modo HTTP.

Configuração - Escolha um método:

Método 1: Usando npx (recomendado - sem necessidade de instalação)

# Quick start
npx @ankimcp/anki-mcp-server

# With custom options
npx @ankimcp/anki-mcp-server --port 8080 --host 0.0.0.0
npx @ankimcp/anki-mcp-server --anki-connect http://localhost:8765

Método 2: Usando instalação global

# Install once
npm install -g @ankimcp/anki-mcp-server

# Run the server
ankimcp

# With custom options
ankimcp --port 8080 --host 0.0.0.0
ankimcp --anki-connect http://localhost:8765

Método 3: Instalar a partir do código fonte (para desenvolvimento)

npm install
npm run build
npm run start:prod:http

Para tornar um servidor HTTP local acessível por uma IA hospedada na nuvem, use uma das opções Remotas abaixo.

Remoto

Um assistente de IA hospedado/remoto (como ChatGPT ou Claude.ai rodando na nuvem) não consegue acessar localhost diretamente. Estas opções expõem seu Anki local à internet para que um assistente remoto possa se comunicar com ele.

Túnel (✅ Recomendado)

Caminho remoto recomendado — autenticado e seguro. Diferente de uma porta pública sem proteção, o modo túnel exige que você faça login (fluxo de dispositivo OAuth 2.0), então o endpoint não fica aberto para qualquer um que adivinhe a URL.

O modo túnel permite que assistentes de IA baseados na web acessem seu Anki local sem que você precise rodar seu próprio túnel. O servidor se conecta ao serviço de túnel gerenciado AnkiMCP (wss://tunnel.ankimcp.ai) via WebSocket e recebe uma URL pública. A autenticação é integrada — não é necessária conta no ngrok nem processo de túnel separado, e você faz login uma única vez.

Fazer login (fluxo de dispositivo OAuth):

O modo túnel usa a Concessão de Autorização de Dispositivo OAuth 2.0. Fazer login abre automaticamente seu navegador em uma página de aprovação com o código já embutido na URL — nada para digitar, apenas aprove. (Se o navegador não puder abrir, o terminal exibe uma URL de verificação e um código para inserir manualmente como alternativa.) Em caso de sucesso, as credenciais são salvas em ~/.ankimcp/credentials.json (permissões de arquivo 0600).

# Pre-authenticate (optional — --tunnel will trigger this automatically if needed)
ankimcp --login
npx @ankimcp/anki-mcp-server --login

# Clear saved credentials
ankimcp --logout

Iniciar o túnel:

# Connect to the managed tunnel service (wss://tunnel.ankimcp.ai)
ankimcp --tunnel
npx @ankimcp/anki-mcp-server --tunnel

# Override the tunnel server URL (must be ws:// or wss://) — e.g. for self-hosting
ankimcp --tunnel wss://my-tunnel.example.com

Se não houver credenciais, --tunnel inicia automaticamente o fluxo de login primeiro e depois prossegue para o túnel. Este login automático requer um terminal interativo — quando a saída padrão não é um TTY (systemd, Docker headless, CI), o servidor falha rapidamente e solicita que você execute ankimcp --login primeiro. Uma vez conectado, a URL pública do túnel é exibida; pressione Ctrl+C para desconectar. Compartilhe essa URL com seu assistente de IA.

Variáveis de ambiente do modo túnel:

Variável	Descrição	Padrão
`TUNNEL_SERVER_URL`	URL do WebSocket do servidor de túnel (o valor da flag `--tunnel`/`--login` sobrescreve isto)	`wss://tunnel.ankimcp.ai`
`TUNNEL_AUTH_CLIENT_ID`	ID do cliente OAuth para o fluxo de dispositivo. Avançado — necessário apenas ao apontar para um serviço de túnel/auth auto-hospedado.	(integrado)

Os endpoints de autenticação do fluxo de dispositivo (/auth/device, /auth/token) são derivados de TUNNEL_SERVER_URL, portanto, apontar --tunnel (ou TUNNEL_SERVER_URL) para um host diferente também move a autenticação para esse host.

Como funciona: O modo túnel executa o servidor MCP em processo por trás de um transporte em memória (McpModule é iniciado sem transporte integrado). TunnelMcpService conecta esse transporte em memória ao servidor MCP, e TunnelClient faz a ponte para o serviço de túnel remoto via WebSocket — retransmitindo solicitações MCP de entrada e respostas de saída. O AnkiConnect ainda é acessado apenas na sua máquina local.

ngrok (alternativa não autenticada)

Se você preferir expor o modo HTTP local publicamente sem uma conta no túnel gerenciado, a flag integrada --ngrok inicia um subprocesso ngrok (src/services/ngrok.service.ts) e exibe a URL pública no banner de inicialização:

# One-time ngrok setup, then:
ankimcp --ngrok

Esta rota não é autenticada — qualquer pessoa com a URL pode acessar seu Anki, portanto, é menos segura que o Túnel. Prefira o Túnel, a menos que você tenha um motivo específico para gerenciar seu próprio endpoint ngrok. (Requer instalação global do ngrok e authtoken.)

A flag --ngrok inicia o ngrok com --host-header=rewrite, então o ngrok reescreve o Host de origem para localhost antes de encaminhar. Isso mantém as solicitações dentro da lista de permissões de Host de loopback (veja proteção contra DNS-rebinding) sem que você precise adicionar o domínio *.ngrok público ao ALLOWED_HOSTS. Se você executar o ngrok manualmente, use a mesma flag — ngrok http --host-header=rewrite 3000 — caso contrário, o ngrok encaminha o nome de host público do ngrok como Host e o servidor o rejeita com 403.

Opções de CLI (todos os modos)

ankimcp [options]

Options:
  --stdio                        Run in STDIO mode (for MCP clients)
  --tunnel [url]                 Connect via the managed tunnel (authenticated)
  --login                        Authenticate for tunnel mode (OAuth device flow)
  --logout                       Clear saved tunnel credentials
  -p, --port <port>              Port to listen on (HTTP mode, default: 3000)
  -h, --host <host>              Host to bind to (HTTP mode, default: 127.0.0.1)
  -a, --anki-connect <url>       AnkiConnect URL (default: http://localhost:8765)
  --ngrok                        Start ngrok tunnel (requires global ngrok installation)
  --read-only                    Run in read-only mode (blocks all write operations)
  --help                         Show help message

Usage with npx (no installation needed):
  npx @ankimcp/anki-mcp-server                        # HTTP mode
  npx @ankimcp/anki-mcp-server --port 8080            # Custom port
  npx @ankimcp/anki-mcp-server --stdio                # STDIO mode
  npx @ankimcp/anki-mcp-server --tunnel               # Managed tunnel mode
  npx @ankimcp/anki-mcp-server --ngrok                # HTTP mode with ngrok tunnel
  npx @ankimcp/anki-mcp-server --read-only            # Read-only mode

Usage with global installation:
  npm install -g @ankimcp/anki-mcp-server             # Install once
  ankimcp                                             # HTTP mode
  ankimcp --port 8080                                 # Custom port
  ankimcp --stdio                                     # STDIO mode
  ankimcp --tunnel                                    # Managed tunnel mode
  ankimcp --ngrok                                     # HTTP mode with ngrok tunnel
  ankimcp --read-only                                 # Read-only mode

Modo Somente Leitura (todos os modos)

A flag --read-only impede qualquer modificação em sua coleção do Anki. Quando ativada:

Todas as operações de leitura funcionam normalmente (navegar por baralhos, visualizar cartões, pesquisar notas)
Operações de revisão são permitidas (sync, answerCards, suspend/unsuspend)
Modificações de conteúdo são bloqueadas (addNote, deleteNotes, createDeck, updateNoteFields, etc.)
Útil para explorar dados do Anki com segurança, sem risco de alterações acidentais

# HTTP mode with read-only
ankimcp --read-only

# STDIO mode with read-only
ankimcp --stdio --read-only

# Can combine with other flags
ankimcp --ngrok --read-only

Você também pode ativar o modo somente leitura via variável de ambiente:

READ_ONLY=true ankimcp

Ou na configuração do cliente MCP:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "npx",
      "args": ["-y", "@ankimcp/anki-mcp-server", "--stdio", "--read-only"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Conectar ao Claude Desktop (Modo Local)

Você pode configurar o servidor no Claude Desktop de duas maneiras:

Acessando: Configurações → Desenvolvedor → Editar Configuração
Ou editando manualmente o arquivo de configuração

Configuração

Adicione o seguinte à sua configuração do Claude Desktop:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": ["/path/to/anki-mcp-server/dist/main-stdio.js"],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Substitua /path/to/anki-mcp-server pelo caminho real do seu projeto.

Locais dos Arquivos de Configuração

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

Para mais detalhes, veja a documentação oficial do MCP.

Variáveis de Ambiente (Opcionais)

Variável	Descrição	Padrão
`ANKI_CONNECT_URL`	URL do AnkiConnect	`http://localhost:8765`
`ANKI_CONNECT_API_VERSION`	Versão da API	`6`
`ANKI_CONNECT_API_KEY`	Chave de API, se configurada no AnkiConnect	-
`ANKI_CONNECT_TIMEOUT`	Tempo limite da solicitação em ms	`5000`
`READ_ONLY`	Ativar modo somente leitura (`true` ou `1`)	`false`
`ALLOWED_HOSTS`	Modo HTTP: valores extras de cabeçalho `Host` a aceitar além de loopback (nomes de host separados por vírgula). Necessário ao vincular a um endereço LAN/público ou executar atrás de um proxy reverso. Veja Configuração do Modo HTTP.	somente loopback
`ALLOWED_ORIGINS`	Modo HTTP: lista de permissões separada por vírgula de padrões de `Origin`/`Referer` do navegador (curingas suportados, ex.: `https://*.ngrok.io`).	`http://localhost:,http://127.0.0.1:,https://localhost:,https://127.0.0.1:`
`TUNNEL_SERVER_URL`	URL do WebSocket do servidor de túnel (somente modo túnel)	`wss://tunnel.ankimcp.ai`
`MEDIA_ALLOWED_TYPES`	Tipos MIME extras a permitir para importações de caminho de arquivo (separados por vírgula, ex.: `application/pdf`)	-
`MEDIA_IMPORT_DIR`	Restringir importações de caminho de arquivo a este diretório	-
`MEDIA_ALLOWED_HOSTS`	Permitir hosts de rede privada específicos para importações de URL (separados por vírgula, ex.: `192.168.1.50,my-nas`)	-

Exemplos de Uso

Pesquisando e Atualizando Notas

# Search for notes in a specific deck
findNotes(query: "deck:Spanish")

# Get detailed information about notes
notesInfo(notes: [1234567890, 1234567891])

# Update a note's fields (HTML content supported)
updateNoteFields(note: {
  id: 1234567890,
  fields: {
    "Front": "<b>¿Cómo estás?</b>",
    "Back": "How are you?"
  }
})

# Delete notes (requires confirmation)
deleteNotes(notes: [1234567890], confirmDeletion: true)

Exemplos de Sintaxe de Consulta do Anki

A ferramenta findNotes suporta a poderosa sintaxe de consulta do Anki:

"deck:DeckName" - Todas as notas em um baralho específico
"tag:important" - Notas com a etiqueta "importante"
"is:due" - Cartões que estão programados para revisão
"is:new" - Cartões novos que não foram estudados
"added:7" - Notas adicionadas nos últimos 7 dias
"front:hello" - Notas com "olá" no campo frontal
"flag:1" - Notas com bandeira vermelha
"prop:due<=2" - Cartões programados para os próximos 2 dias
"deck:Spanish tag:verb" - Notas do baralho Espanhol com etiqueta verbo (E)
"deck:Spanish OR deck:French" - Notas de qualquer um dos baralhos

Notas Importantes

Manipulação de CSS e HTML

A ferramenta notesInfo retorna informações de estilo CSS para percepção adequada da renderização
A ferramenta updateNoteFields suporta conteúdo HTML nos campos e preserva o estilo CSS
Cada modelo de nota tem seu próprio estilo CSS - use modelStyling para obter CSS específico do modelo

Aviso de Atualização

⚠️ IMPORTANTE: Ao usar updateNoteFields, NÃO visualize a nota no navegador do Anki durante a atualização, ou os campos não serão atualizados corretamente. Feche o navegador ou mude para uma nota diferente antes de atualizar. Veja Problemas Conhecidos para mais detalhes.

Segurança na Exclusão

A ferramenta deleteNotes requer confirmação explícita (confirmDeletion: true) para evitar exclusões acidentais. Excluir uma nota remove TODOS os cartões associados permanentemente.

Segurança

Validação de Caminho de Arquivo de Mídia e URL

As ferramentas de mídia (storeMediaFile, retrieveMediaFile, deleteMediaFile) e campos de áudio/imagem updateNoteFields incluem validação de segurança para prevenir uso indevido via injeção de prompt:

Importações de caminho de arquivo são restritas apenas a tipos de arquivo de mídia (imagens, áudio, vídeo). Arquivos não midiáticos (ex.: chaves SSH, credenciais, configurações de shell) são rejeitados com base no tipo MIME. Configure MEDIA_ALLOWED_TYPES para permitir tipos de arquivo adicionais, ou MEDIA_IMPORT_DIR para restringir importações a um diretório específico.
Importações de URL são validadas contra ataques SSRF. Solicitações para redes privadas (10.x, 172.16.x, 192.168.x), loopback (127.x), link-local (169.254.x) e esquemas não HTTP(S) são bloqueadas. Configure MEDIA_ALLOWED_HOSTS para permitir hosts de rede privada específicos.
Nomes de arquivo são sanitizados para prevenir travessia de caminho (ex.: sequências ../../ são removidas).

Estas proteções se aplicam a storeMediaFile, retrieveMediaFile, deleteMediaFile e campos de áudio/imagem updateNoteFields.

Vulnerabilidade de travessia de caminho relatada por Hideaki Takahashi.

Proteção contra DNS-Rebinding (transporte HTTP)

Ao executar no modo HTTP, o servidor valida o cabeçalho Host em cada solicitação. Por padrão, apenas hosts de loopback (localhost, 127.0.0.1, ::1) são aceitos, independentemente da porta. Host é um cabeçalho proibido pelo navegador, então uma página web maliciosa não pode forjá-lo — isso fecha o caminho de DNS-rebinding onde uma página redirecionada alcança o servidor local com um Host falsificado e sem Origin, e acessa as ferramentas MCP. Um Host não permitido é rejeitado com 403.

Se você vincular a 0.0.0.0, executar atrás de um proxy reverso ou expor um domínio de túnel público, defina ALLOWED_HOSTS (nomes de host separados por vírgula) para permitir esses hosts. Ao usar túnel com ngrok, o servidor usa --host-header=rewrite, então o upstream ainda vê um Host de loopback. Veja Configuração do Modo HTTP para a lista completa de opções.

Vulnerabilidade de DNS-rebinding relatada por avishaigo-commits e yotampe-pluto.

Política de Privacidade

Este servidor MCP é executado localmente em sua máquina e não coleta telemetria, análises ou dados de uso.

Política completa: https://ankimcp.ai/privacy/

Coleta de dados: O servidor não coleta nada. Ele faz proxy de solicitações entre seu assistente de IA e seu plugin AnkiConnect local.
Uso / armazenamento: Sem armazenamento no lado do servidor. Todos os dados de flashcards permanecem em sua instalação do Anki no seu próprio dispositivo.
Compartilhamento com terceiros: Nenhum. O servidor apenas se comunica com a URL do AnkiConnect que você configurar (padrão: localhost). Se você ativar a sincronização integrada do AnkiWeb do Anki, isso ocorre entre sua instalação do Anki e o AnkiWeb diretamente — fora do escopo deste servidor.
Retenção: Não aplicável — nenhum dado é retido no lado do servidor.
Contato: support@ankimcp.ai

Problemas Conhecidos

Para uma lista abrangente de problemas conhecidos e limitações, visite nossa documentação:

Documentação de Problemas Conhecidos

Limitações Críticas

Atualizações de Notas Falham Quando Visualizadas no Navegador

⚠️ IMPORTANTE: Ao atualizar notas usando updateNoteFields, a atualização falhará silenciosamente se a nota estiver sendo visualizada na janela do navegador do Anki. Esta é uma limitação do AnkiConnect.

Solução alternativa: Sempre feche o navegador ou navegue para uma nota diferente antes de atualizar.

Para mais detalhes e outros problemas conhecidos, veja a documentação completa.

Solução de Problemas

Erro ERR_REQUIRE_ESM

Se você vir um erro como:

Error [ERR_REQUIRE_ESM]: require() of ES Module not supported

Isso significa que sua versão do Node.js não é suportada. O servidor requer Node.js 22.12.0+.

Nota: O tempo de execução mínimo suportado é Node.js 22.12.0. Node.js 20 (Iron) chegou ao fim da vida útil em 30/04/2026 e não é mais suportado.

Verifique sua versão:

node --version

Solução: Atualize o Node.js para a versão 22.12.0+. Você pode baixá-lo em nodejs.org ou usar um gerenciador de versões como nvm.

Desenvolvimento

Modos de Transporte

Este servidor suporta três modos de transporte MCP por meio de pontos de entrada separados:

Modo STDIO (Padrão)

Para clientes MCP locais como o Claude Desktop
Usa entrada/saída padrão para comunicação
Ponto de entrada: dist/main-stdio.js
Executar: npm run start:prod:stdio ou node dist/main-stdio.js
Pacote MCPB: Usa o modo STDIO

Modo HTTP (HTTP Transmissível)

Para clientes MCP remotos e integrações baseadas na web
Usa o protocolo MCP Streamable HTTP
Ponto de entrada: dist/main-http.js
Executar: npm run start:prod:http ou node dist/main-http.js
Porta padrão: 3000 (configurável via variável de ambiente PORT)
Host padrão: 127.0.0.1 (configurável via variável de ambiente HOST)
Endpoint MCP: http://127.0.0.1:3000/ (caminho raiz)

Modo Túnel (Túnel WebSocket Gerenciado)

Para assistentes de IA baseados na web através do serviço de túnel gerenciado AnkiMCP, com autenticação integrada
O servidor MCP é executado em processo por trás de um transporte em memória; TunnelMcpService o conecta ao servidor MCP e TunnelClient faz a ponte para o serviço de túnel via WebSocket
Ponto de entrada: dist/main-tunnel.js
Executar: node dist/main-tunnel.js --tunnel (ou ankimcp --tunnel)
Autenticação: ankimcp --login / ankimcp --logout; credenciais armazenadas em ~/.ankimcp/credentials.json (0600)
Desenvolvimento: npm run start:dev:tunnel (modo observação, executa --tunnel --debug)

Compilação

npm run build  # Builds once, creates dist/ with all three entry points

main-stdio.js, main-http.js e main-tunnel.js são todos compilados no mesmo diretório dist/. Escolha qual executar com base em suas necessidades.

Configuração do Modo HTTP

Variáveis de Ambiente:

PORT - Porta do servidor HTTP (padrão: 3000)
HOST - Endereço de vinculação (padrão: 127.0.0.1 para somente localhost)
ALLOWED_HOSTS - Valores extras de cabeçalho Host separados por vírgula a serem aceitos além do conjunto de loopback integrado (localhost, 127.0.0.1, ::1). Somente nome de host e independente de porta. Padrão: somente loopback.
ALLOWED_ORIGINS - Lista de permissões separada por vírgulas de padrões de Origin/Referer do navegador; curingas suportados (ex.: https://*.ngrok.io). Padrão: http://localhost:*,http://127.0.0.1:*,https://localhost:*,https://127.0.0.1:*.
LOG_LEVEL - Nível de registro (padrão: info)

Segurança:

Validação do cabeçalho Host (proteção contra DNS-rebinding) — toda requisição HTTP deve conter um cabeçalho Host que corresponda à lista de permissões. Por padrão, apenas hosts de loopback (localhost, 127.0.0.1, ::1) são aceitos, independentemente da porta. Host é um cabeçalho proibido pelo navegador, portanto uma página web maliciosa não pode forjá-lo — isso fecha o caminho de DNS-rebinding onde uma página redirecionada alcança o servidor com um Host falsificado e sem Origin. Um Host não permitido é rejeitado com 403.
Validação do cabeçalho Origin — requisições do navegador com um Origin/Referer presente, mas não permitido, são rejeitadas. Requisições sem Origin (curl, Postman, clientes MCP-over-HTTP) são permitidas; a validação do Host é a defesa contra rebinding.
Vincula-se ao localhost (127.0.0.1) por padrão.
Sem autenticação na versão atual (suporte a OAuth planejado).

Expondo o modo HTTP além do localhost — se você vincular a um endereço LAN/público ou colocar o servidor atrás de um proxy reverso ou domínio público, você deve definir ALLOWED_HOSTS para o(s) nome(s) de host que os clientes usarão, caso contrário, toda requisição não loopback será rejeitada com 403:

# Bind to all interfaces and accept the machine's LAN name + a public domain
ALLOWED_HOSTS=my-nas.local,anki.example.com PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Quando você vincula a 0.0.0.0/:: sem ALLOWED_HOSTS, o servidor registra um aviso de inicialização de que apenas cabeçalhos Host de loopback serão aceitos.

Docker / proxy reverso / domínio público: a mesma regra se aplica. No Docker, as requisições geralmente chegam com o nome de host publicado do contêiner ou o Host do proxy, então defina ALLOWED_HOSTS de acordo. Um proxy reverso (nginx, Caddy, Traefik) deve encaminhar o Host original e ter esse nome de host listado em ALLOWED_HOSTS, ou reescrever o Host upstream para localhost. A integração integrada com --ngrok lida com isso automaticamente (veja abaixo).

Exemplo: Executando Modos

# Development - STDIO mode (watch mode with auto-rebuild)
npm run start:dev:stdio

# Development - HTTP mode (watch mode with auto-rebuild)
npm run start:dev:http

# Production - STDIO mode
npm run start:prod:stdio
# or
node dist/main-stdio.js

# Production - HTTP mode
npm run start:prod:http
# or
PORT=8080 HOST=0.0.0.0 node dist/main-http.js

Construindo um Pacote MCPB

Para criar um pacote MCPB distribuível:

npm run mcpb:bundle

Este comando irá:

Sincronizar a versão de package.json para manifest.json
Remover arquivos .mcpb antigos
Compilar o projeto TypeScript
Empacotar dist/ e node_modules/ em um arquivo .mcpb
Executar mcpb clean para remover devDependencies (otimiza o pacote de ~47MB para ~10MB)

O arquivo de saída será nomeado anki-mcp-server-X.X.X.mcpb e pode ser distribuído para instalação com um clique.

O Que é Empacotado

O pacote MCPB inclui:

JavaScript compilado (diretório dist/ - inclui todos os três pontos de entrada)
Apenas dependências de produção (node_modules/ - devDependencies removidas por mcpb clean)
Metadados do pacote (package.json)
Configuração do manifesto (manifest.json - configurado para usar main-stdio.js)
Ícone (icon.png)

Arquivos fonte, testes e configurações de desenvolvimento são automaticamente excluídos via .mcpbignore.

Registro de Logs no Claude Desktop

Ao executar como uma extensão MCPB no Claude Desktop, os logs são gravados em:

Localização do Log: ~/Library/Logs/Claude/ (macOS)

Os logs são divididos em vários arquivos:

main.log - Logs gerais da aplicação Claude Desktop
mcp-server-Anki MCP Server.log - Mensagens do protocolo MCP para esta extensão
mcp.log - Logs MCP combinados de todos os servidores

Nota: A saída do logger pino (mensagens INFO, ERROR, WARN do código do servidor) vai para stderr e aparece nos arquivos de log específicos do MCP. O Claude Desktop determina qual arquivo de log recebe quais mensagens, mas geralmente:

Inicialização da aplicação e comunicação do protocolo MCP → Log específico do MCP
Logging interno do servidor (pino) → Tanto o log específico do MCP quanto, às vezes, main.log

Para visualizar logs em tempo real:

tail -f ~/Library/Logs/Claude/mcp-server-Anki\ MCP\ Server.log

Depurando o Servidor MCP

Você pode depurar o servidor MCP usando o MCP Inspector e anexando um depurador do seu IDE (WebStorm, VS Code, etc.).

Nota para o Modo HTTP: Ao testar o modo HTTP (HTTP Transmissível) com o MCP Inspector, use "Connection Type: Via Proxy" para evitar erros de CORS.

Passo 1: Configurar Servidor de Depuração no MCP Inspector

O mcp-inspector-config.json já inclui uma configuração de servidor de depuração:

{
  "mcpServers": {
    "stdio-server-debug": {
      "type": "stdio",
      "command": "node",
      "args": ["--inspect-brk=9229", "dist/main-stdio.js"],
      "env": {
        "MCP_SERVER_NAME": "anki-mcp-stdio-debug",
        "MCP_SERVER_VERSION": "1.0.0",
        "LOG_LEVEL": "debug"
      },
      "note": "Anki MCP server with debugging enabled on port 9229"
    }
  }
}

Passo 2: Iniciar o Servidor de Depuração

Execute o MCP Inspector com o servidor de depuração:

npm run inspector:debug

Isso iniciará o servidor com a depuração do Node.js habilitada na porta 9229 e pausará a execução na primeira linha.

Passo 3: Anexar Depurador do Seu IDE

WebStorm

Vá para Run → Edit Configurations
Adicione uma nova configuração Attach to Node.js/Chrome
Defina a porta como 9229
Clique em Debug para anexar

VS Code

Abra o painel de Depuração (Ctrl+Shift+D / Cmd+Shift+D)
Selecione a configuração Debug MCP Server (Attach)
Pressione F5 para anexar

Passo 4: Definir Pontos de Interrupção e Depurar

Uma vez anexado, você pode:

Definir pontos de interrupção em seus arquivos fonte TypeScript
Avançar passo a passo pela execução do código
Inspecionar variáveis e pilha de chamadas
Usar o console de depuração para avaliar expressões

O depurador funcionará com mapas de fonte, permitindo depurar o código TypeScript original em vez do JavaScript compilado.

Depurando com o Claude Desktop

Você também pode depurar o servidor MCP enquanto ele é executado dentro do Claude Desktop, habilitando o depurador do Node.js e anexando seu IDE.

Passo 1: Configurar o Claude Desktop para Depuração

Atualize sua configuração do Claude Desktop para habilitar a depuração:

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

{
  "mcpServers": {
    "anki-mcp": {
      "command": "node",
      "args": [
        "--inspect=9229",
        "<path_to_project>/anki-mcp-server/dist/main-stdio.js"
      ],
      "env": {
        "ANKI_CONNECT_URL": "http://localhost:8765"
      }
    }
  }
}

Mudança chave: Adicione --inspect=9229 antes do caminho para dist/main-stdio.js

Opções de depuração:

--inspect=9229 - Inicia o depurador imediatamente, não bloqueia (recomendado)
--inspect-brk=9229 - Pausa a execução até que o depurador seja anexado (para depurar problemas de inicialização)

Passo 2: Reiniciar o Claude Desktop

Após salvar a configuração, reinicie o Claude Desktop. O servidor MCP agora será executado com depuração habilitada na porta 9229.

Passo 3: Anexar Depurador do Seu IDE

WebStorm

Vá para Run → Edit Configurations
Clique no botão + e selecione Attach to Node.js/Chrome
Configure:
- Name: Attach to Anki MCP (Claude Desktop)
- Host: localhost
- Port: 9229
- Attach to: Node.js < 8 ou Chrome or Node.js > 6.3 (dependendo da versão do WebStorm)
Clique em OK
Clique em Debug (Shift+F9) para anexar

VS Code

Adicione ao .vscode/launch.json:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "attach",
      "name": "Attach to Anki MCP (Claude Desktop)",
      "port": 9229,
      "skipFiles": ["<node_internals>/**"],
      "sourceMaps": true,
      "outFiles": ["${workspaceFolder}/dist/**/*.js"]
    }
  ]
}

Abra o painel de Depuração (Ctrl+Shift+D / Cmd+Shift+D)
Selecione Attach to Anki MCP (Claude Desktop)
Pressione F5 para anexar

Passo 4: Depurar em Tempo Real

Uma vez anexado, você pode:

Definir pontos de interrupção em seus arquivos fonte TypeScript (ex.: src/mcp/primitives/essential/tools/create-model.tool.ts)
Usar o Claude Desktop normalmente - os pontos de interrupção serão atingidos quando as ferramentas forem invocadas
Avançar passo a passo pela execução do código
Inspecionar variáveis e pilha de chamadas
Usar o console de depuração

Exemplo: Defina um ponto de interrupção em create-model.tool.ts na linha 119 e, em seguida, peça ao Claude para criar um novo modelo. O depurador pausará no seu ponto de interrupção!

Nota: O depurador permanece anexado enquanto o Claude Desktop estiver em execução. Você pode desanexar/reanexar a qualquer momento sem reiniciar o Claude Desktop.

Comandos de Compilação

npm run build              # Build the project (compile TypeScript to JavaScript)
npm run start:dev:stdio    # STDIO mode with watch (auto-rebuild)
npm run start:dev:http     # HTTP mode with watch (auto-rebuild)
npm run type-check         # Run TypeScript type checking
npm run lint               # Run ESLint
npm run mcpb:bundle        # Sync version, clean, build, and create MCPB bundle

Teste do Pacote NPM (Local)

Teste o pacote npm localmente antes de publicar:

# 1. Create local package
npm run pack:local         # Builds and creates @ankimcp/anki-mcp-server-*.tgz

# 2. Install globally from local package
npm run install:local      # Installs from ./@ankimcp/anki-mcp-server-*.tgz

# 3. Test the command
ankimcp                    # Runs HTTP server on port 3000

# 4. Uninstall when done testing
npm run uninstall:local    # Removes global installation

Como funciona:

npm pack cria um arquivo .tgz idêntico ao que o npm publish criaria
Instalar a partir de .tgz simula o que os usuários obtêm de npm install -g ankimcp
Isso permite testar a experiência completa do usuário antes de publicar no npm

Comandos de Teste

npm test              # Run all tests
npm run test:unit     # Run unit tests only
npm run test:tools    # Run tool-specific tests
npm run test:workflows # Run workflow integration tests
npm run test:e2e      # Run end-to-end tests
npm run test:cov      # Run tests with coverage report
npm run test:watch    # Run tests in watch mode
npm run test:debug    # Run tests with debugger
npm run test:ci       # Run tests for CI (silent, with coverage)

Cobertura de Testes

O projeto mantém limites mínimos de cobertura de 70% para:

Ramificações
Funções
Linhas
Declarações

Relatórios de cobertura são gerados no diretório coverage/.

Versionamento

Este projeto segue Versionamento Semântico com uma abordagem de desenvolvimento pré-1.0:

0.x.x - Versões Beta/Desenvolvimento (fase atual)
- 0.1.x - Correções de bugs e patches
- 0.2.0+ - Novos recursos ou pequenas melhorias
- Mudanças quebradiças são aceitáveis nas versões 0.x
1.0.0 - Primeiro lançamento estável
- Será lançado quando a API estiver estável e testada
- Mudanças quebradiças exigirão incrementos de versão principal (2.0.0, etc.)

Status Atual: 0.22.0 - Desenvolvimento beta ativo. Recursos recentes incluem análise de revisão em toda a coleção (review_stats agora agrega em todos os decks quando deck é omitido), gerenciamento de campos de modelo (addModelField, removeModelField, renameModelField, repositionModelField), criação de notas em lote (addNotes), tunelamento ngrok integrado (flag --ngrok), gerenciamento de arquivos de mídia, gerenciamento de modelo/modelo e estatísticas abrangentes de deck. As APIs podem mudar com base em feedback e testes.

Evolução da especificação MCPB

Este projeto visa a especificação de pacote MCPB da Anthropic, que ainda está evoluindo. Acompanhamos a especificação em https://github.com/modelcontextprotocol/mcpb e podemos introduzir mudanças quebradiças para permanecer em conformidade. Mudanças quebradiças são permitidas sob o esquema de versionamento 0.x.x.

Projetos Similares

Se você está explorando integrações Anki MCP, aqui estão outros projetos neste espaço:

scorzeth/anki-mcp-server

Status: Parece estar abandonado (sem atualizações recentes)
Implementação inicial da integração Anki MCP

nailuoGG/anki-mcp-server

Abordagem: Implementação leve, em arquivo único
Arquitetura: Estrutura de código procedural com todas as ferramentas em um arquivo
Bom para: Casos de uso simples, dependências mínimas Por que este projeto é diferente:
Arquitetura de nível empresarial: Construído sobre NestJS com injeção de dependência
Design modular: Cada ferramenta é uma classe separada com clara separação de responsabilidades
Manutenibilidade: Fácil de estender com novos recursos sem alterar o código existente
Testes: Suíte de testes abrangente com exigência de 70% de cobertura
Segurança de tipos: TypeScript estrito com validação Zod
Tratamento de erros: Tratamento robusto de erros com feedback útil ao usuário
Pronto para produção: Registro de logs adequado, relatório de progresso e suporte a pacotes MCPB
Escalabilidade: Pode crescer facilmente de ferramentas básicas para fluxos de trabalho complexos

Caso de uso: Se você precisa de uma base sólida para construir integrações avançadas com o Anki ou planeja estender a funcionalidade significativamente, a abordagem arquitetural deste projeto facilita a manutenção e a escalabilidade ao longo do tempo.

Links Úteis

Licença e Atribuição

Este projeto está licenciado sob a Licença MIT — veja LICENSE para o texto completo.

Atribuições de Terceiros

Anki® é uma marca registrada da Ankitects Pty Ltd. Este projeto é uma ferramenta de terceiros não oficial e não é afiliado, endossado ou patrocinado pela Ankitects Pty Ltd. O logotipo do Anki é usado sob a licença alternativa para referenciar o Anki com um link para https://apps.ankiweb.net. Para o aplicativo oficial do Anki, visite https://apps.ankiweb.net.
Model Context Protocol (MCP) é um padrão aberto da Anthropic. O logotipo do MCP é do repositório oficial de documentação do MCP e é usado sob a Licença MIT. Para mais informações sobre o MCP, visite https://modelcontextprotocol.io.
Este é um projeto independente que conecta as tecnologias Anki e MCP. Todas as marcas registradas, marcas de serviço, nomes comerciais, nomes de produtos e logotipos são propriedade de seus respectivos titulares.