Mousetaile

Servidor MCP do Anki

GitHub
16
Experimente este MCPPatrocinado

Documentação

Mousetail Logo

O servidor MCP mais simples e estável para Anki

UV Python 3.10+ MCP License: MIT

O objetivo do Mousetail é ser a forma mais simples e confiável de conectar o Anki a um LLM. Ele não requer nenhum addon, basta ter o Anki instalado e um LLM que você queira conectar aos seus baralhos.

Executar o servidor é tão simples quanto:

uvx mousetail

Para instruções detalhadas sobre integração com Claude Code, Claude Desktop e outras ferramentas de LLM:

Guia de Uso

Referência da API

Recursos

  • Mínimo - suporta operações principais do Anki: criar, ler, atualizar e excluir
  • Estável - funciona diretamente com a API estável pylib do Anki, sem addons ou dependências
  • Simples - não requer configuração, descobre automaticamente suas coleções do Anki

Casos de Uso

Comitar seletivamente o que você aprende em conversas com um LLM para a memória

"Crie um baralho baseado na nossa conversa para eu não esquecer detalhes críticos"

Use um LLM para interagir com seu baralho

"Crie um cartão - o que é um coeficiente?, crie um cartão - identifique o primeiro coeficiente neste polinômio"

Use um LLM para limpar um baralho

"Verifique meu baralho de vocabulário de francês quanto à correção e corrija quaisquer erros, erros de digitação ou enganos"

Sincronização

O Mousetail suporta sincronizar sua coleção do Anki com o AnkiWeb ou um servidor de sincronização auto-hospedado. Isso permite que você mantenha sua coleção sincronizada entre dispositivos.

Início Rápido

Sincronize com o AnkiWeb (salva as credenciais para sincronizações futuras):

> "Save my AnkiWeb credentials: username is myuser@example.com and password is mypassword"
> "Sync my collection with AnkiWeb"

Gerenciamento de Credenciais

O Mousetail armazena credenciais com segurança no gerenciador de credenciais do seu sistema:

  • macOS: Keychain
  • Windows: Gerenciador de Credenciais
  • Linux: Secret Service (GNOME Keyring, KWallet, etc.)

Ferramentas de credenciais disponíveis:

  • save_sync_credentials - Salvar nome de usuário/senha com segurança
  • load_sync_credentials - Carregar credenciais salvas
  • delete_sync_credentials - Remover credenciais salvas

Opções de Sincronização

A ferramenta sync_collection suporta:

  • Sincronização AnkiWeb (padrão) - Deixe o endpoint vazio
  • Servidores auto-hospedados - Forneça uma URL de endpoint personalizada (ex.: https://sync.example.com)
  • Sincronização de mídia - Habilitada por padrão, inclui imagens e arquivos de áudio
  • Sincronização apenas da coleção - Defina sync_media: false para pular a mídia

Exemplos

Configuração inicial com AnkiWeb:

> "Save my sync credentials for AnkiWeb - username: user@example.com, password: mypass123"
> "Sync my collection"

Usando um servidor auto-hospedado:

> "Save my sync credentials - username: john, password: secret, endpoint: https://sync.myserver.com"
> "Sync my collection"

Sincronização única sem salvar credenciais:

> "Sync my collection with AnkiWeb using username user@example.com and password mypass123"

Sincronização apenas da coleção (pular mídia):

> "Sync my collection but don't sync media files"

Configuração

Você pode definir um endpoint de sincronização padrão em config.json:

{
  "sync": {
    "endpoint": "https://sync.example.com"
  }
}

Deixe endpoint como null para usar o AnkiWeb por padrão.

Notas Importantes

  • Feche o Anki primeiro: A sincronização falhará se o aplicativo Anki estiver em execução
  • Sincronização de mídia: A sincronização de mídia é mais lenta e usa mais largura de banda, mas garante que imagens/áudio sejam sincronizados
  • Conflitos: Se ocorrerem conflitos, tente sincronizar pelo desktop do Anki primeiro para resolvê-los
  • Segurança: As credenciais nunca são armazenadas em texto simples - elas são mantidas no armazenamento seguro de credenciais do seu sistema

Configuração do Servidor de Sincronização Auto-Hospedado

Para sincronizar com seu próprio servidor:

  1. Configure um servidor de sincronização Anki
  2. Configure as credenciais no servidor (usando variáveis de ambiente como SYNC_USER1=user:password)
  3. Salve suas credenciais no Mousetail com o endpoint do servidor
  4. Sincronize normalmente

Para configuração detalhada do servidor de sincronização, consulte a documentação oficial do Anki.

Notas Importantes

Como as Coleções São Acessadas

O servidor MCP encontra as coleções do Anki em seus locais padrão:

  • macOS: ~/Library/Application Support/Anki2/[Profile]/collection.anki2
  • Linux: ~/.local/share/Anki2/[Profile]/collection.anki2
  • Windows: %APPDATA%\Anki2\[Profile]\collection.anki2

Você não precisa configurar caminhos - o servidor descobre automaticamente as coleções disponíveis, isso pode ser personalizado usando configuração.

Configuração

O servidor pode ser personalizado através de um arquivo config.json. Consulte o Guia de Uso para opções de configuração.

Desenvolvimento

Configuração de Desenvolvimento Local

Para desenvolver e testar o Mousetail localmente com Claude Code:

  1. Clone o repositório:

    git clone https://github.com/listfold/mousetail.git
cd mousetail

  2. Instale as dependências:

    uv sync

  3. Configure o Claude Code: O projeto inclui um arquivo .mcp.json que configura o servidor MCP para desenvolvimento local:

    {
  "mcpServers": {
    "mousetail": {
      "type": "stdio",
      "command": "uv",
      "args": ["run", "python", "-m", "mousetail.mcp.stdio_server"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

  4. Reinicie o Claude Code: Após a configuração estar no lugar, reinicie o Claude Code para carregar o servidor MCP.

  5. Verifique o servidor:

    • Use /context no Claude Code para ver as ferramentas MCP disponíveis
    • O servidor mousetail deve aparecer com todas as ferramentas disponíveis (list_collections, create_note, sync_collection, etc.)

  6. Testando a funcionalidade de sincronização:

    • Feche o aplicativo desktop do Anki antes de testar
    • Teste o gerenciamento de credenciais: save_sync_credentials, load_sync_credentials, delete_sync_credentials
    • Teste a sincronização: sync_collection com suas credenciais do AnkiWeb ou servidor auto-hospedado

Objetivos principais

O Mousetail foi escrito porque todas as ferramentas MCP Anki existentes dependem do addon AnkiConnect.

O AnkiConnect é um servidor HTTP para Anki, foi originalmente criado para suportar a conexão de extensões de navegador como yomichan ao Anki. Para desenvolvimento MCP, não é necessário e introduz problemas:

  • introduz complexidade, ex.: um servidor HTTP dedicado para Anki ocupa uma porta
  • introduz risco, ex.: se a API do AnkiConnect mudar ou tiver um bug, a ferramenta MCP quebrará
  • introduz uma etapa extra, ex.: todas as ferramentas MCP atuais exigem a instalação do addon AnkiConnect

O Mousetail tem uma abordagem muito mais simples. Ele integra diretamente com o pylib do Anki. Esta é uma API estável que faz parte do núcleo do Anki, portanto não está sujeita a mudanças arbitrárias ou frequentes, e não requer nenhum addon de terceiros.

Como prioriza a simplicidade, o mousetail permanecerá mais estável que as alternativas. A compensação é que o Mousetail nunca se integrará à interface do Anki. Também é razoável assumir que o Mousetail só funcionará com ferramentas LLM e baralhos Anki no mesmo sistema (colocalizados).

Construindo Documentação

O projeto usa Sphinx com o tema Furo para gerar documentação a partir de docstrings Python.

  1. Instale as dependências de documentação:

    uv pip install ".[docs]"

  2. Construa a documentação:

    uv run python -m sphinx -b html docs docs/_build/html

  3. Veja a documentação: Abra docs/_build/html/index.html no seu navegador.

A documentação é automaticamente construída e implantada no GitHub Pages a cada push para o branch main.

Licença

Licença MIT - veja o arquivo LICENSE para detalhes.