FastMail

Interaja com o e-mail, calendário e contatos do FastMail por meio de sua API JMAP.

Documentação

Servidor MCP FastMail

Um servidor Model Context Protocol (MCP) para integração com a API JMAP do FastMail. Este servidor fornece ferramentas para ler e-mails, pesquisar, gerenciar pastas e enviar e-mails através do FastMail.

🚀 Recursos

📁 Gerenciamento de Caixas de Entrada: Listar e encontrar caixas de entrada/pastas
📧 Leitura de E-mails: Obter e-mails de pastas específicas com pré-visualizações
🔍 Pesquisa Avançada: Pesquisar por palavra-chave, remetente, assunto, intervalo de datas, anexos
📤 Envio de E-mails: Enviar e-mails com suporte a CC/CCO
🎯 Direcionamento de Pastas: Pesquisar dentro de pastas específicas
⚡ Desempenho Rápido: Utiliza o protocolo JMAP moderno do FastMail

📋 Pré-requisitos

Python 3.8+
Conta FastMail com acesso à API
Token de API do FastMail (Configurações → Privacidade e Segurança → Integrações)

🛠 Instalação

Clone o repositório:

git clone <your-repo-url>
cd fastmail-mcp-server

Instale as dependências:
```
pip install -r requirements.txt
```
Obtenha seu token de API do FastMail:
- Faça login no FastMail
- Vá para Configurações → Privacidade e Segurança → Integrações
- Crie um novo token de API
- Copie o token (começa com fmu1-)

🚀 Uso

Executando o Servidor

python fastmail_mcp_server.py

O servidor iniciará e aguardará comandos MCP via stdio.

Configuração

Primeiro, configure suas credenciais do FastMail:

{
  "tool": "configure_fastmail",
  "arguments": {
    "apiToken": "fmu1-your-token-here"
  }
}

Ferramentas Disponíveis

📁 configure_fastmail

Configure suas credenciais de API do FastMail.

📁 list_mailboxes

Liste todas as caixas de entrada com seus nomes, funções e contagens de e-mails.

{
  "tool": "list_mailboxes",
  "arguments": {
    "role": "inbox"  // Optional: filter by role
  }
}

🔍 find_mailbox

Encontre uma caixa de entrada específica por nome ou função.

{
  "tool": "find_mailbox", 
  "arguments": {
    "name": "Work",     // Partial matching supported
    "role": "sent"      // Or search by role
  }
}

📧 get_emails

Obtenha e-mails de uma caixa de entrada específica.

{
  "tool": "get_emails",
  "arguments": {
    "mailboxId": "mailbox-id-here",  // From list_mailboxes
    "mailboxName": "Inbox",          // Alternative to mailboxId
    "limit": 20,                     // Max emails to fetch
    "includeBody": false             // Include full email body
  }
}

🔍 search_emails

Pesquise e-mails com filtros avançados.

{
  "tool": "search_emails",
  "arguments": {
    "keyword": "project update",     // Text search
    "from_email": "boss@company.com", // From specific sender
    "subject": "meeting",            // Subject contains
    "mailboxId": "inbox-id",         // Search within folder
    "hasAttachment": true,           // Has attachments
    "after": "2024-01-01",          // Date range
    "before": "2024-12-31",
    "limit": 50,
    "includeBody": false
  }
}

📖 get_email_body

Obtenha o conteúdo completo do corpo de um e-mail específico.

{
  "tool": "get_email_body",
  "arguments": {
    "emailId": "email-id-here",
    "format": "text"  // "text", "html", or "both"
  }
}

📤 send_email

Envie um e-mail através do FastMail.

{
  "tool": "send_email",
  "arguments": {
    "to": ["recipient@example.com"],
    "cc": ["cc@example.com"],        // Optional
    "bcc": ["bcc@example.com"],      // Optional  
    "subject": "Hello from MCP!",
    "body": "This is the email body.",
    "isHtml": false                  // Set to true for HTML emails
  }
}

🔧 Integração com Clientes MCP

Claude Desktop

Adicione à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "fastmail": {
      "command": "python",
      "args": ["/path/to/fastmail_mcp_server.py"]
    }
  }
}

Outros Clientes MCP

Este servidor segue o protocolo MCP padrão e deve funcionar com qualquer cliente compatível com MCP.

🏗 Estrutura do Projeto

fastmail-mcp-server/
├── fastmail_mcp_server.py    # Main server implementation
├── requirements.txt          # Python dependencies
├── pyproject.toml           # Package configuration
├── README.md                # This file
└── examples/                # Example usage scripts
    └── test_server.py       # Test script

🔒 Notas de Segurança

Segurança do Token de API: Nunca envie seu token de API para o controle de versão
Permissões: O token de API tem acesso a toda a sua conta FastMail
Rede: Toda a comunicação usa HTTPS com as APIs seguras do FastMail

🐛 Solução de Problemas

Problemas Comuns

Erro de Autenticação: Verifique se seu token de API está correto e possui as permissões adequadas
Erro de Conexão: Verifique sua conexão com a internet e o status do serviço FastMail
E-mails Ausentes: Certifique-se de que está pesquisando na caixa de entrada correta

Modo de Depuração

Ative o registro de depuração definindo a variável de ambiente:

export MCP_DEBUG=1
python fastmail_mcp_server.py

🤝 Contribuindo

Faça um fork do repositório
Crie um branch de recurso
Faça suas alterações
Adicione testes, se aplicável
Envie um pull request