local-fastmail-mcp

Servidor MCP Local Fastmail

IMPORTANTE: a partir de abril de 2026, a Fastmail possui seu próprio servidor MCP oficial. Veja o anúncio em https://www.fastmail.com/blog/an-mcp-server-for-fastmail/

Vou arquivar este repositório e sugerir que você opte pela opção oficial. Estou deixando o código online como exemplo de boas práticas para validação de dados com Zod e desenvolvimento de MCP stdio em TypeScript.

Um servidor Model Context Protocol hospedado localmente que conecta sua conta Fastmail a qualquer assistente de IA compatível com MCP (como Claude Desktop, Cursor ou ferramentas similares).

Esta integração aproveita a API JMAP nativa da Fastmail e esquemas estritamente tipados em TypeScript/Zod para permitir que seu assistente de IA leia, gerencie e interaja com sua caixa de entrada sem depender de integrações de webhooks de terceiros ou expor credenciais externamente.

Recursos

Uma vez conectado, seu assistente de IA pode usar as seguintes ferramentas:

list_mailboxes

Descubra todos os rótulos, pastas e caixas de correio da sua conta. Retorna o ID, nome, função, contagens de não lidos/totais e permissões de cada caixa de correio.

list_emails

Consulte e-mails por pasta, busca por palavras-chave ou status de lido/não lido. Suporta paginação para grandes conjuntos de resultados.

Parâmetro	Tipo	Descrição
mailboxId	string?	Filtrar por um ID específico de caixa de correio (use list_mailboxes para descobrir IDs)
query	string?	Busca de texto completo no conteúdo do e-mail
unreadOnly	boolean?	Retornar apenas e-mails não lidos
limit	number?	Máximo de resultados por página (padrão: 20, máximo: 250)
position	number?	Deslocamento baseado em zero para paginação

A resposta inclui emails, total, position e hasMore. Para percorrer os resultados, incremente position por limit a cada chamada até que hasMore seja false.

read_email

Busque o conteúdo completo de um e-mail específico pelo seu ID.

Parâmetro	Tipo	Descrição
emailId	string	O ID exato do e-mail a ser lido
textOnly	boolean?	Quando true, busca apenas conteúdo text/plain, ignorando HTML. Ideal para newsletters e e-mails com muito HTML para reduzir o tamanho da resposta.

send_email

Redija e envie um novo e-mail a partir da sua conta Fastmail.

Parâmetro	Tipo	Descrição
to	string	Endereço de e-mail de destino
subject	string	Linha de assunto
body	string	Corpo do conteúdo em texto simples

mark_email_read

Marque um e-mail específico como lido ou não lido.

Parâmetro	Tipo	Descrição
emailId	string	O ID exato do e-mail
read	boolean?	true para marcar como lido (padrão), false para não lido

move_email

Transfira um e-mail para uma caixa de correio/pasta diferente.

Parâmetro	Tipo	Descrição
emailId	string	O ID exato do e-mail a ser movido
mailboxId	string	O ID da caixa de correio de destino

delete_email

Mova um e-mail para a caixa de correio Lixeira.

Parâmetro	Tipo	Descrição
emailId	string	O ID exato do e-mail a ser excluído

---

Abordagem de Segurança

Este servidor usa exclusivamente transporte stdio — ele nunca expõe uma porta HTTP externa. As credenciais são armazenadas localmente no seu arquivo .env ou passadas via configuração de ambiente do cliente MCP. Toda a comunicação é diretamente entre sua máquina local e os endpoints oficiais api.fastmail.com/jmap.

---

Instalação e Configuração

1. Requisitos

Certifique-se de ter instalado Node.js (versão 22+ recomendada) e npm na sua máquina local.

2. Configure seu Token de API Fastmail

1. Faça login na sua conta Fastmail.
2. Vá para Settings -> Privacy & Security -> Connected apps & API tokens.
3. Clique em Novo Token de API.
4. Dê um nome ao token (ex.: "Servidor MCP de IA")
5. Forneça ao token os seguintes escopos:
   • Email (necessário para leitura e listagem)
   • Email submission (necessário para envio de e-mails)
6. Copie o token de API gerado com segurança.

3. Configuração Local do Projeto

Clone o repositório e instale as dependências necessárias:

npm install

Copie o arquivo de exemplo de variáveis de ambiente:

cp .env.example .env

Abra .env no seu editor de texto e cole suas credenciais:

FASTMAIL_EMAIL=your_email@fastmail.com
FASTMAIL_API_TOKEN=fmu1-your-secret-token-here

4. Compile o Projeto

Compile o framework TypeScript para a lógica de execução nativa em JavaScript:

npm run build

---

Conectando a um Cliente MCP

Este servidor funciona com qualquer cliente compatível com MCP. Abaixo está um exemplo usando Claude Desktop.

Claude Desktop

1. Abra o Claude Desktop e escolha Configurações -> Desenvolvedor -> Editar Config Abra claude_desktop_config.json

2. Adicione isso à seção mcpServers, corrigindo o caminho para o arquivo index.js compilado e adicionando suas próprias credenciais:

{
  "mcpServers": {
    "local-fastmail": {
      "command": "node",
      "args": ["/absolute/path/to/your/local-fastmail-mcp/dist/index.js"],
      "env": {
        "FASTMAIL_EMAIL": "your_email@fastmail.com",
        "FASTMAIL_API_TOKEN": "fmu1-your-secret-token-here"
      }
    }
  }
}

3. Reinicie o Claude Desktop. As novas ferramentas aparecerão instantaneamente e você pode começar a digitar "Resuma meus 20 e-mails não lidos mais recentes."

Para outros clientes MCP, consulte a documentação deles sobre como registrar um servidor stdio local apontando para dist/index.js com as variáveis de ambiente necessárias.

---

Desenvolvimento e Testes

Este projeto é construído usando TypeScript, @modelcontextprotocol/sdk e parsing Zod.

Se você estiver desenvolvendo novas ferramentas ou fazendo ajustes nos recursos da Fastmail:

1. Compilação: Sempre certifique-se de executar npm run build após fazer modificações.
2. Testes: Execute o harness nativo de cobertura Vitest executando:

npm test

Pull requests são bem-vindos! Por favor, abra uma issue primeiro para discutir o que você gostaria de mudar. Pretendo ser criterioso, no entanto, então sinta-se à vontade também para fazer um fork e criar sua própria versão.