Anki MCP Server

Interaja com o aplicativo de flashcards Anki por meio do complemento AnkiConnect. Suporta geração de áudio e busca por similaridade.

GitHub

Experimente este MCPPatrocinado

Documentação

Anki MCP Server

Um servidor FastMCP para interagir com o Anki através do Model Context Protocol (MCP). Este servidor fornece ferramentas abrangentes para gerenciar baralhos (decks), notas e tipos de nota do Anki, com recursos avançados incluindo geração de áudio com IA, operações em lote e busca por similaridade semântica.

APIs Externas Utilizadas

Este projeto integra-se com várias APIs externas para fornecer funcionalidades aprimoradas:

Google Cloud Text-to-Speech API

Finalidade: Geração de áudio de alta qualidade a partir de texto usando as vozes Chirp do Google
Caso de Uso: Gerar arquivos de áudio de pronúncia para flashcards
Recursos: Vozes de qualidade HD com pronúncia natural, especialmente excelentes para chinês
Configuração: Requer a variável de ambiente GOOGLE_CLOUD_API_KEY

AnkiConnect API (Local)

Finalidade: Interface com o aplicativo de desktop do Anki
Caso de Uso: Todas as operações do Anki (criar/ler/atualizar notas, gerenciar baralhos, etc.)
Recursos: Funcionalidade completa do Anki via API HTTP
Configuração: O add-on AnkiConnect deve estar instalado e o Anki deve estar em execução

Configuração

Instale as dependências usando uv:
```
uv sync
```
Certifique-se de que o Anki esteja em execução com o add-on AnkiConnect instalado:
- No Anki, vá em Ferramentas > Complementos > Obter complementos
- Insira o código: 2055492159
- Reinicie o Anki

(Opcional) Configure a chave de API para geração de áudio:

# For audio generation with Google Cloud TTS
export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Execute o servidor:
```
uv run server.py
```

Integração com Claude Desktop

Para usar este servidor MCP com o Claude Desktop, adicione a seguinte configuração ao seu arquivo claude_desktop_config.json:

Localização da Configuração

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

Exemplo de Configuração

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ],
      "env": {
        "GOOGLE_CLOUD_API_KEY": "your-google-cloud-api-key-here"
      }
    }
  }
}

Etapas de Configuração

Garanta que as dependências estejam instaladas: Certifique-se de ter executado uv sync no seu diretório anki-mcp
Encontre seu arquivo de configuração no local acima (crie-o se não existir)
Atualize o caminho: Substitua /path/to/your/anki-mcp/ pelo caminho real do seu diretório anki-mcp
Adicione sua chave de API:
- Substitua your-google-cloud-api-key-here pela sua chave de API real do Google Cloud (para geração de áudio)
Reinicie o Claude Desktop para que as alterações tenham efeito

Notas Importantes

Certifique-se de que o Anki esteja em execução com o add-on AnkiConnect antes de usar as ferramentas
O comando uv lidará automaticamente com o ambiente Python e as dependências
Certifique-se de que uv esteja instalado no seu sistema (curl -LsSf https://astral.sh/uv/install.sh | sh)

Alternativa: Usando Variáveis de Ambiente

Se você preferir manter sua chave de API no ambiente do shell, pode omitir a seção env:

{
  "mcpServers": {
    "anki-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/your/anki-mcp/",
        "run",
        "server.py"
      ]
    }
  }
}

Em seguida, defina a variável de ambiente no seu shell:

export GOOGLE_CLOUD_API_KEY='your-google-cloud-api-key-here'

Verificação

Após a configuração, reinicie o Claude Desktop e você deverá ver as ferramentas do Anki MCP disponíveis em suas conversas. Você pode verificar pedindo ao Claude para listar seus baralhos do Anki ou experimentar qualquer uma das ferramentas disponíveis.

Ferramentas Disponíveis

`list_decks`

Lista todos os baralhos do Anki disponíveis com contagem.

Parâmetros: Nenhum

Retorna: String formatada com todos os nomes dos baralhos e contagem total

`get_deck_notes`

Recupera todas as notas/cartões de um baralho específico com informações detalhadas.

Parâmetros:

deck_name (str): Nome do baralho do Anki do qual recuperar as notas

Retorna: Informações detalhadas sobre todas as notas, incluindo nome do modelo, tags e valores dos campos

`get_deck_sample`

Obtém uma amostra aleatória de notas de um baralho para entender a estrutura típica das notas.

Parâmetros:

deck_name (str): Nome do baralho do Anki do qual amostrar notas
sample_size (int, opcional): Número de notas para amostrar (1-50, padrão: 5)

Retorna: Informações detalhadas sobre as notas amostradas

`get_deck_note_types`

Analisa um baralho para identificar todos os tipos de nota (modelos) e suas definições de campos.

Parâmetros:

deck_name (str): Nome do baralho do Anki a ser analisado

Retorna: Todos os tipos de nota exclusivos usados no baralho com seus nomes de campos

`create_note`

Cria uma nova nota no baralho especificado.

Parâmetros:

deck_name (str): Nome do baralho do Anki ao qual adicionar a nota
model_name (str): Nome do tipo de nota/modelo a ser usado
fields (dict): Dicionário mapeando nomes de campos para valores (ex.: {'Front': 'Question', 'Back': 'Answer'})
tags (list, opcional): Lista opcional de tags para adicionar à nota

Retorna: Objeto JSON com noteId e status de sucesso ou mensagem de erro

`update_note`

Atualiza campos específicos de uma nota existente preservando os demais campos.

Parâmetros:

note_id (int): ID da nota a ser atualizada
fields (dict): Dicionário mapeando nomes de campos para novos valores (ex.: {'Audio': '[sound:pronunciation.mp3]'})
tags (list, opcional): Lista opcional de tags para substituir as tags existentes

Retorna: Objeto JSON com status de sucesso e informações dos campos atualizados

Caso de Uso: Perfeito para adicionar arquivos de áudio a cartões existentes ou atualizar conteúdo específico

`create_deck_with_note_type`

Cria um novo baralho e, opcionalmente, um novo tipo de nota com campos e modelos personalizados.

Parâmetros:

deck_name (str): Nome para o novo baralho do Anki
model_name (str): Nome para o tipo de nota/modelo
fields (list): Lista de nomes de campos (ex.: ['Front', 'Back', 'Extra'])
card_templates (list, opcional): Lista opcional de definições de modelos de cartão

Retorna: Objeto JSON com status de criação e detalhes

`list_note_types`

Lista todos os tipos de nota (modelos) disponíveis com informações abrangentes.

Parâmetros: Nenhum

Retorna: Informações sobre todos os tipos de nota, incluindo campos, modelos e estilos

`generate_audio`

Gera arquivos de áudio de alta qualidade a partir de texto usando a API Google Cloud Text-to-Speech com vozes Chirp.

Parâmetros:

text (str): Texto a ser convertido em fala
language (str, opcional): Código do idioma (padrão: "cmn-cn" para chinês)
voice (str, opcional): Nome da voz (padrão: "cmn-CN-Chirp3-HD-Achernar" para voz HD em chinês)

Retorna: Objeto JSON com dados de áudio MP3 codificados em base64 e metadados

Configuração: Requer a variável de ambiente GOOGLE_CLOUD_API_KEY

Recursos: Vozes de qualidade HD com pronúncia natural, especialmente excelentes para aprendizado de chinês

`save_media_file`

Salva dados de mídia codificados em base64 como um arquivo na coleção de mídia do Anki para uso em cartões.

Parâmetros:

filename (str): Nome do arquivo a ser salvo (ex.: 'audio.mp3', 'image.jpg')
base64_data (str): Dados do arquivo codificados em base64
media_type (str, opcional): Tipo de arquivo de mídia (padrão: "audio")

Retorna: Objeto JSON com nome do arquivo salvo e status de sucesso

Caso de Uso: Salvar áudio gerado ou outros arquivos de mídia para uso em cartões do Anki

`generate_and_save_audio`

Gera áudio a partir de texto e o salva diretamente na coleção de mídia do Anki em uma única operação.

Parâmetros:

text (str): Texto a ser convertido em fala e salvo
filename (str): Nome para o arquivo de áudio (ex.: 'pronunciation.mp3')
language (str, opcional): Código do idioma (padrão: "cmn-cn" para chinês)
voice (str, opcional): Nome da voz (padrão: "cmn-CN-Chirp3-HD-Achernar")

Retorna: Objeto JSON com nome do arquivo e tag de som para uso nos campos do cartão

Configuração: Requer a variável de ambiente GOOGLE_CLOUD_API_KEY

Caso de Uso: Geração e salvamento de áudio em uma única etapa, retorna a tag [sound:filename.mp3] pronta para os campos do cartão

`create_notes_bulk`

Cria múltiplas notas em uma única operação em lote para máxima eficiência. Lida com duplicatas de forma elegante, reportando quais notas são duplicatas enquanto ainda cria as notas não duplicadas. NOVO: Opcionalmente, gera automaticamente arquivos de áudio usando Google TTS para cada nota.

Parâmetros:

deck_name (str): Nome do baralho do Anki ao qual adicionar as notas
notes_list (list): Lista de dicionários de notas, cada um contendo 'model_name', 'fields' e, opcionalmente, 'tags'
auto_audio (AutoAudioConfig ou null, opcional): IMPORTANTE: Passe como um dicionário/objeto com a estrutura mostrada abaixo, NÃO como uma string JSON. Configuração para geração automática de áudio:
- enabled (bool, obrigatório): Deve ser true para habilitar a geração de áudio
- source_field (str, obrigatório): Nome do campo do qual ler o texto (ex.: "Front", "Hanzi")
- target_field (str, obrigatório): Nome do campo no qual escrever a tag de áudio (ex.: "Audio")
- language (str, opcional): Código do idioma - padrão "cmn-cn" para chinês
- voice (str, opcional): Nome da voz - padrão "cmn-CN-Chirp3-HD-Achernar"
Formato correto (objeto dicionário):
```
{
  "enabled": true,
  "source_field": "Hanzi",
  "target_field": "Audio",
  "language": "cmn-cn",
  "voice": "cmn-CN-Chirp3-HD-Achernar"
}
```
ERRADO - NÃO passe como string:
```
"{\"enabled\": true, \"source_field\": \"Hanzi\", ...}"  ❌ INCORRECT
```
Para desabilitar a geração de áudio, passe null ou omita este parâmetro completamente.

Retorna: Objeto JSON com contagens de sucesso/falha, array de notas bem-sucedidas, array de notas com falha e resultados da geração de áudio se habilitada

Recursos:

Usa canAddNotesWithErrorDetail para pré-verificar quais notas podem ser adicionadas
Apenas tenta adicionar notas válidas, garantindo que não haja falhas em lote
Fornece relatórios de erro detalhados para cada nota com falha (duplicatas, erros de validação, etc.)
Retorna IDs das notas criadas com sucesso para processamento adicional
Gera automaticamente arquivos de áudio para todas as notas em uma única operação - sem necessidade de criar notas e depois atualizá-las separadamente!
A geração de áudio reporta sucesso/falha para cada nota individualmente
Pula a geração de áudio se o campo de destino já tiver conteúdo

Caso de Uso: Criar 20 cartões de vocabulário chinês com áudio em uma única operação eficiente em vez de criar cartões e depois atualizar cada um individualmente

`update_notes_bulk`

Atualiza múltiplas notas em uma única operação em lote para máxima eficiência.

Parâmetros:

updates (list): Lista de dicionários de atualização, cada um contendo 'note_id', dicionário 'fields' e, opcionalmente, lista 'tags'

Retorna: Objeto JSON com contagens de sucesso/falha e resultados detalhados da atualização

Caso de Uso: Perfeito para atualizações em lote, como adicionar arquivos de áudio a vários cartões de uma vez

`find_similar_notes`

Encontra notas que contêm o texto de busca como substring em qualquer campo. Correspondência de texto simples e confiável.

Parâmetros:

deck_name (str): Nome do baralho do Anki no qual buscar
search_text (str): Texto a ser buscado como substring em qualquer campo
case_sensitive (bool, opcional): Se a busca deve diferenciar maiúsculas de minúsculas (padrão: false)
max_results (int, opcional): Número máximo de notas correspondentes a retornar (padrão: 20)

Retorna: Objeto JSON com notas correspondentes e detalhes sobre quais campos continham o texto de busca

Recursos:

Correspondência rápida de substring em todos os campos das notas
Opções de busca com ou sem diferenciação de maiúsculas/minúsculas
Mostra exatamente quais campos corresponderam aos critérios de busca
Nenhuma dependência de API externa necessária

Detalhes Técnicos

Framework: FastMCP (construído sobre FastAPI)
Nome do Servidor: "anki-mcp"
URL do AnkiConnect: http://localhost:8765
Dependências: fastapi, fastmcp, requests, uvicorn
APIs Externas:
- Google Cloud Text-to-Speech API (para geração de áudio)
Formato de Áudio: MP3 com codificação base64

Recursos

Geração de Áudio HD: TTS de qualidade premium usando vozes Google Cloud Chirp, otimizado para pronúncia chinesa
Geração Automática de Áudio em Lote: Crie notas com áudio em uma única operação - sem necessidade de criar notas e depois adicionar áudio separadamente!
Atualizações de Notas: Atualize notas existentes com novo conteúdo, como arquivos de áudio, preservando outros campos
Gerenciamento de Mídia: Integração direta com a coleção de mídia do Anki para manipulação perfeita de arquivos
Operações em Lote: Criação e atualização eficiente de notas em lote para grandes conjuntos de dados
Busca Rápida de Texto: Correspondência simples de substrings para encontrar notas contendo texto específico
Tratamento Abrangente de Erros: Tratamento robusto de erros para todas as falhas de API e casos extremos
Formatação Inteligente de Dados: Truncamento e formatação de conteúdo para legibilidade ideal
Amostragem Aleatória: Amostragem eficiente para grandes conjuntos de dados sem problemas de memória
Modelos Personalizados: Suporte completo para modelos de cartões personalizados e estilos CSS
Segurança de Tipos: Validação completa de parâmetros usando Pydantic
Manuseio Seguro de Chave de API: Gerenciamento de chave de API baseado em variáveis de ambiente
Tratamento Robusto de Erros: Pré-validação de notas com relatórios detalhados de erros para duplicatas e outros problemas
Suporte a Vários Idiomas: Otimizado para aprendizado de chinês, mas suporta vários idiomas