Mektup mcp
Mektup é uma plataforma de e-mail auto-hospedada e multi-domínio. Este servidor MCP permite que um agente de codificação de IA (Claude Code, Claude Desktop, Cursor, Lovable, Replit, Base44 ou qualquer cliente compatível com MCP) gerencie e-mails reais para um domínio.
Documentação
Servidor MCP Mektup
Mektup é uma plataforma de e-mail multi-domínio totalmente gerenciada — a Mektup hospeda toda a infraestrutura de e-mail, então não há nada para auto-hospedar; você apenas se cadastra e usa. Este servidor MCP permite que um agente de IA de codificação (Claude Code, Claude Desktop, Cursor, Lovable, Replit, Base44 ou qualquer cliente compatível com MCP) gerencie e-mails reais para um domínio — registre-o, adicione os registros DNS, crie caixas de correio, envie e leia e-mails, gerencie rascunhos/contatos/pastas/encaminhamento/respostas de férias — como chamadas de ferramentas nativas dentro de sua própria sessão, em vez de um humano escrever manualmente comandos curl ou colar uma chave de API em código gerado.
Cada chamada de ferramenta é uma chamada HTTP direta para a API REST da Mektup real. Não há lógica separada para aprender — se você entende a API, entende o servidor MCP. Cobertura completa: cada endpoint REST tem uma ferramenta correspondente, verificada com idas e voltas reais de leitura e escrita contra a API de produção ao vivo (criar → atualizar → listar → excluir, confirmado em cada etapa).
Duas maneiras de executá-lo, mesmo conjunto de ferramentas em ambos os casos (lib/build-server.js define as ferramentas uma vez, compartilhado por ambos):
- Remoto (HTTP Streamable) — um servidor que hospedamos em
https://mcp.usemektup.com/mcp. Aponte qualquer cliente que aceite uma URL de "servidor MCP personalizado" diretamente para ele, sem instalação. É isso que plataformas estilo Lovable/Cursor/Replit/Base44 querem. - Local (stdio) — execute
server.jsvocê mesmo com sua chave em uma variável de ambiente. Para clientes MCP que só suportam iniciar um processo local (config do Claude Desktop, etc.).
Servidor remoto (recomendado para integrações de plataforma)
Endpoint: https://mcp.usemektup.com/mcp (HTTP Streamable — suporta tanto os modos de resposta JSON direta quanto streaming SSE da especificação).
Sem estado: nenhuma sessão é mantida entre requisições — cada chamada de ferramenta já é um repasse único para a API REST, então não há estado de sessão que valha a pena manter.
Isolamento de locatário: idêntico à API REST, porque é a API REST por baixo — o servidor não mantém nenhuma credencial específica da conta, ele apenas encaminha o token que o chamador enviou (chave de API ou token de acesso OAuth, veja abaixo) diretamente para api.usemektup.com, que é o único lugar que realmente o verifica. Um token só vê os dados da própria conta.
Dois modos de autenticação, mesmo endpoint, ambos chegam como o mesmo cabeçalho Authorization: Bearer <token>:
OAuth (recomendado para integrações de plataforma)
Para uma plataforma com usuários finais reais (Lovable, Cursor, Replit, Base44, ...) — o usuário clica em "conectar", faz login com sua conta Mektup existente, aprova, pronto. Sem copiar e colar token, sem visitar o painel.
Clerk (clerk.usemektup.com) é o servidor de autorização OAuth 2.1 — este servidor MCP é apenas um servidor de recursos. A descoberta é automática para qualquer cliente MCP compatível com OAuth e em conformidade com a especificação: ele só precisa da URL do endpoint acima e encontra o resto sozinho via https://mcp.usemektup.com/.well-known/oauth-protected-resource/mcp (RFC 9728), que aponta para o próprio https://clerk.usemektup.com/.well-known/oauth-authorization-server do Clerk (RFC 8414). A partir daí, o cliente se registra via Dynamic Client Registration (sem configuração manual necessária do seu lado) e executa um fluxo padrão de Authorization Code + PKCE, terminando com um token de acesso JWT usado exatamente como uma chave de API.
Lovable: Connectors → All → Custom (cartão MCP) → Server Name Mektup, Server URL https://mcp.usemektup.com/mcp, Auth → OAuth (padrão quando um servidor suporta) → Add & authorize.
Chave de API (mais simples para uma única conta, scripts ou um cliente sem suporte a OAuth)
Authorization: Bearer mek_live_... — crie uma em app.usemektup.com → API keys.
Adicioná-la a um cliente que suporta conectores MCP personalizados normalmente são 3 campos:
| Campo | Valor |
|---|---|
| URL do servidor | https://mcp.usemektup.com/mcp |
| Tipo de autenticação | Bearer token / API key |
| Token | sua chave mek_live_... |
Cursor / Claude Desktop / qualquer cliente que lê configuração MCP JSON bruta:
{
"mcpServers": {
"mektup": {
"url": "https://mcp.usemektup.com/mcp",
"headers": { "Authorization": "Bearer mek_live_..." }
}
}
}
Replit / Base44 / outros fluxos de "conectar uma ferramenta": os mesmos três campos da tabela acima — URL do servidor, autenticação Bearer, chave.
Configuração local (stdio)
Use isto quando um cliente só puder iniciar um processo local, não chamar uma URL remota.
1. Obtenha uma chave de API. Faça login no painel em app.usemektup.com, abra API keys e crie uma. As chaves parecem com mek_live_... e são mostradas apenas uma vez — copie imediatamente.
2. Instale as dependências:
git clone https://github.com/WeeCi/mektup-mcp.git
cd mektup-mcp
npm install
3. Configure seu cliente MCP para executar server.js com a chave como variável de ambiente. Para Claude Desktop / Claude Code, adicione à sua configuração MCP (ex.: claude_desktop_config.json):
{
"mcpServers": {
"mektup": {
"command": "node",
"args": ["/absolute/path/to/mektup-mcp/server.js"],
"env": {
"MEKTUP_API_KEY": "mek_live_..."
}
}
}
}
MEKTUP_API_BASE_URL é opcional e o padrão é https://api.usemektup.com — não há necessidade de defini-lo em uso normal.
O servidor se recusa a iniciar sem MEKTUP_API_KEY definido.
Como as ferramentas respondem
Cada ferramenta retorna seu resultado como texto JSON em caso de sucesso. Em caso de falha, retorna isError: true com Error: <message> — a mensagem é a mesma que o endpoint REST subjacente retornou (veja a referência da API para condições de erro exatas, incluindo 402s de limite de cobrança, por endpoint).
Ferramentas
Conta
| Ferramenta | Entrada | Descrição |
|---|---|---|
get_me | — | Obter a identidade da conta autenticada. Útil como verificação de saúde da autenticação. |
get_usage | — | Nível de cobrança atual, seus limites e uso real contra eles. Verifique antes de uma operação em massa. |
Chaves de API
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_api_keys | — | Listar chaves nesta conta (apenas prefixo e status). |
create_api_key | — | Criar uma nova chave. A chave completa é retornada apenas uma vez — mostre-a ao usuário imediatamente para que ele possa salvá-la. |
revoke_api_key | id | Revogar uma chave imediatamente. Não pode ser desfeito — confirme com o usuário primeiro, especialmente se puder ser a chave que esta própria sessão está usando. |
Domínios
| Ferramenta | Entrada | Descrição |
|---|---|---|
create_domain | domain | Registrar um domínio, receber de volta os registros DNS exatos (MX/SPF/DMARC/DKIM) e uma recomendação de configuração. Nunca toca no DNS em si. |
list_domains | — | Listar todos os domínios nesta conta. |
get_domain_records | domain | Buscar novamente os registros DNS de um domínio registrado a qualquer momento após a criação. |
verify_domain | domain | Verificar ativamente o DNS ao vivo e mudar para verificado quando corresponder. Não é automático. |
delete_domain | domain | Excluir um domínio e tudo sob ele. Destrutivo — confirme com o usuário primeiro. |
Caixas de correio
| Ferramenta | Entrada | Descrição |
|---|---|---|
create_mailbox | domain, localPart, password? | Criar uma caixa de correio com credenciais reais de IMAP/SMTP-AUTH, utilizável em qualquer cliente de e-mail. |
list_mailboxes | domain | Listar caixas de correio em um domínio. |
reset_mailbox_password | domain, localPart, password? | Redefinir a senha de login de uma caixa de correio. Mostrada uma vez. |
delete_mailbox | domain, localPart | Excluir uma caixa de correio. Confirme com o usuário primeiro. |
Webhooks
| Ferramenta | Entrada | Descrição |
|---|---|---|
get_mailbox_webhook | domain, localPart | Verificar a URL de webhook configurada de uma caixa de correio (nunca retorna o segredo de assinatura). |
set_mailbox_webhook | domain, localPart, url, regenerateSecret? | Definir/atualizar a URL que dispara (assinada com HMAC) em cada nova mensagem recebida — como um agente descobre novos e-mails sem fazer polling em list_messages. Retorna o segredo de assinatura uma vez, na configuração inicial ou rotação. |
delete_mailbox_webhook | domain, localPart | Remover o webhook de uma caixa de correio. |
Encaminhamento
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_forwards | domain, localPart | Listar endereços que recebem uma cópia do e-mail recebido. |
add_forward | domain, localPart, forwardTo | Adicionar um endereço de encaminhamento. |
remove_forward | domain, localPart, id | Remover um endereço de encaminhamento. |
Identidade
| Ferramenta | Entrada | Descrição |
|---|---|---|
get_identity | domain, localPart | Obter nome de exibição e assinatura. |
set_identity | domain, localPart, displayName?, signatureText?, signatureHtml? | Definir nome de exibição/assinatura, aplicados automaticamente ao e-mail de saída. |
Férias / resposta automática
| Ferramenta | Entrada | Descrição |
|---|---|---|
get_vacation | domain, localPart | Obter configurações de resposta automática de férias. |
set_vacation | domain, localPart, enabled, subject?, message? | Ativar/configurar resposta automática. message obrigatório ao ativar. |
Pastas
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_folders | domain, localPart | Listar pastas personalizadas. |
create_folder | domain, localPart, name | Criar uma pasta. |
delete_folder | domain, localPart, id | Excluir uma pasta (os e-mails nela voltam para Entrada/Enviados). |
Contatos
Nível de conta, não por caixa de correio.
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_contacts | — | Listar contatos. |
create_contact | name?, email | Adicionar um contato. |
update_contact | id, name?, email? | Atualização parcial — envie apenas os campos a alterar. |
delete_contact | id | Excluir um contato. |
Rascunhos
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_drafts | domain, localPart | Listar rascunhos (apenas metadados). |
get_draft | domain, localPart, id | Obter um rascunho incluindo seu corpo. |
create_draft | domain, localPart, to?, subject?, text?, html? | Criar um rascunho. |
update_draft | domain, localPart, id, to?, subject?, text?, html? | Atualização parcial (amigável para salvamento automático). |
delete_draft | domain, localPart, id | Excluir um rascunho. |
Envio
| Ferramenta | Entrada | Descrição |
|---|---|---|
send_email | from, to, subject, text?, html?, attachments?, draftId? | Enviar e-mail real. from deve ser uma caixa de correio nesta conta, ou qualquer endereço em um domínio que esta conta tenha verificado. Anexos são {filename, contentType?, contentBase64}, máx. 10MB decodificados cada. Passe draftId para excluir um rascunho após envio bem-sucedido. |
Exemplo:
send_email({ from: "hello@example.com", to: "you@gmail.com", subject: "It works", text: "Real mail, sent through Mektup." })
→ { "messageId": "<...@example.com>", "envelope": { "from": "hello@example.com", "to": ["you@gmail.com"] } }
Mensagens e conversas
| Ferramenta | Entrada | Descrição |
|---|---|---|
list_messages | mailbox, limit?, direction?, trash?, folder?, q? | Lista mensagens (uma linha por thread). Passe direction para dividir Caixa de Entrada/Enviados — omitir mescla ambos. |
get_delivery_stats | mailbox, days? | Agrega contagens de enviados/adiados/devolvidos/desconhecidos para o e-mail de saída de uma caixa postal, com base no log de entrega Postfix do próprio Mektup — não é um pixel de rastreamento. |
get_thread | threadKey, mailbox, direction?, trash?, folder? | Todas as mensagens em uma thread, da mais antiga para a mais recente. |
get_message | id | Conteúdo completo da mensagem. Marca como lida como efeito colateral. html é controlado pelo atacante — nunca renderize diretamente. |
update_message | id, read?, restore?, flagged?, folderId? | Marca como lida/não lida, restaura da lixeira, sinaliza ou move para uma pasta — qualquer combinação em uma única chamada. |
delete_message | id | Exclusão em duas etapas: a primeira chamada move para a lixeira, a segunda chamada em uma mensagem já na lixeira exclui permanentemente. Confirme antes de uma exclusão permanente. |
download_attachment | id, index | Baixa um anexo, codificado em base64. Prefira apenas quando o conteúdo real do arquivo for necessário — a lista de anexos de get_message já possui nome/tipo/tamanho. |
Em toda a conta
| Ferramenta | Entrada | Descrição |
|---|---|---|
get_unread_counts | — | Contagem de não lidas na Caixa de Entrada para todos os domínios/caixas postais de uma vez. |
Veja também
- Referência completa da API REST — tudo que este servidor encapsula
- Especificação OpenAPI 3.1 — versão legível por máquina da mesma API
- usemektup.com — cadastro, painel, preços
Licença
MIT