Guia prático
Executar o servidor MCP localmente
Execute o pacote de código aberto @emailit/emailit-mcp via stdio ou HTTP local com uma chave de API e configure o Claude, o Cursor e o VS Code para usá-lo.
@emailit/emailit-mcp é a versão de código aberto do servidor MCP do Emailit. Ele é executado na sua máquina, se comunica com a API do Emailit usando a sua chave de API e funciona com clientes que só aceitam servidores locais (stdio). A maioria das pessoas deve usar o servidor hospedado; esta página explica quando o pacote local faz sentido e como configurá-lo.
- Pacote:
@emailit/emailit-mcpno npm - Código-fonte: github.com/emailit/emailit-mcp, licença MIT
- Runtime: Node.js 18 ou mais recente
Local ou hospedado
| Pacote local | Servidor hospedado | |
|---|---|---|
| Onde é executado | Na sua máquina, iniciado pelo seu cliente MCP | Em https://api.emailit.com/mcp |
| Login | Apenas chave de API | OAuth ou chave de API |
| Ferramentas | O conjunto original: e-mails, domínios, chaves de API, listas de contatos, contatos, templates, supressões e webhooks | 109, toda a API v2, incluindo campanhas, automações, formulários, DMARC, verificação e eventos |
| Workspaces | O workspace da chave de API | Vários workspaces por conexão com OAuth, escolhidos a cada pedido |
| Papéis e escopos | O escopo da chave de API | O seu papel em cada workspace e o escopo aprovado |
| Remetente e endereço de resposta padrão | Configuráveis | Não disponíveis; o assistente passa from em cada envio |
| Atualizações | Você controla a versão que executa | Automáticas |
Escolha o pacote local quando:
- o seu cliente só aceita servidores stdio ou não consegue usar OAuth com servidores remotos,
- você quer um endereço From e um Reply-To padrão aplicados a todos os envios, ou
- você quer ler, fixar a versão ou modificar o código do servidor.
Antes de começar
- Node.js 18 ou mais recente, para ter o
npxdisponível. - Uma chave de API. Use uma chave Sending Only, restrita a um domínio, se o assistente só precisar enviar; as outras ferramentas precisam de Full Access.
- Um domínio de envio verificado para o endereço do remetente.
Configurar o seu cliente
O cliente inicia o servidor como um subprocesso e se comunica com ele via stdio. Passe a chave de API pela variável de ambiente EMAILIT_API_KEY.
claude mcp add emailit \
-e EMAILIT_API_KEY=secret_•••••••• \
-e SENDER_EMAIL_ADDRESS=hello@acme.com \
-- npx -y @emailit/emailit-mcpAbra Settings > Developer > Edit Config, adicione o servidor ao claude_desktop_config.json e depois reinicie o Claude Desktop:
{
"mcpServers": {
"emailit": {
"command": "npx",
"args": ["-y", "@emailit/emailit-mcp"],
"env": {
"EMAILIT_API_KEY": "secret_••••••••",
"SENDER_EMAIL_ADDRESS": "hello@acme.com"
}
}
}
}Adicione o servidor a ~/.cursor/mcp.json ou ao .cursor/mcp.json de um projeto:
{
"mcpServers": {
"emailit": {
"command": "npx",
"args": ["-y", "@emailit/emailit-mcp"],
"env": {
"EMAILIT_API_KEY": "secret_••••••••",
"SENDER_EMAIL_ADDRESS": "hello@acme.com"
}
}
}
}Adicione o servidor a .vscode/mcp.json. O VS Code pede a chave e a guarda com segurança:
{
"inputs": [
{ "type": "promptString", "id": "emailit-api-key", "description": "Emailit API key", "password": true }
],
"servers": {
"emailit": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@emailit/emailit-mcp"],
"env": {
"EMAILIT_API_KEY": "${input:emailit-api-key}",
"SENDER_EMAIL_ADDRESS": "hello@acme.com"
}
}
}
}Use sempre o nome do pacote com escopo, @emailit/emailit-mcp.
Variáveis de ambiente
| Variável | Obrigatória | Descrição |
|---|---|---|
EMAILIT_API_KEY |
No modo stdio | A sua chave de API do Emailit. No modo HTTP, cada cliente envia a própria chave. |
SENDER_EMAIL_ADDRESS |
Não | Endereço From padrão, em um domínio de envio verificado. |
REPLY_TO_EMAIL_ADDRESSES |
Não | Endereços Reply-To padrão, separados por vírgula. |
MCP_PORT |
Não | Porta do modo HTTP. O padrão é 3000. |
Se você não definir um remetente, o servidor pede ao assistente um endereço From em cada envio.
Flags de linha de comando
As flags substituem as variáveis de ambiente correspondentes.
| Flag | Descrição |
|---|---|
--key <key> |
Chave de API para o modo stdio. |
--sender <email> |
Endereço From padrão. |
--reply-to <email> |
Endereço Reply-To padrão. Repita a flag para vários endereços. |
--http |
Serve Streamable HTTP em vez de stdio. |
--port <port> |
Porta para --http. O padrão é 3000 ou MCP_PORT. |
-h, --help |
Mostra as instruções de uso. |
Executar via HTTP
Para compartilhar um único servidor local entre vários clientes, inicie-o no modo HTTP:
npx -y @emailit/emailit-mcp --http --port 3000O servidor escuta em http://127.0.0.1:3000/mcp e só pode ser acessado a partir da sua máquina. Cada cliente se autentica com a própria chave de API como bearer token:
claude mcp add emailit --transport http http://127.0.0.1:3000/mcp \
--header "Authorization: Bearer $EMAILIT_API_KEY"Executar a partir do código-fonte
git clone https://github.com/emailit/emailit-mcp.git
cd emailit-mcp
npm install
EMAILIT_API_KEY=secret_•••••••• node src/index.jsAdicione --http --port 3000 ao último comando para o modo HTTP.
Solução de problemas
| Problema | Solução |
|---|---|
API key is required for stdio mode. Use --key or set EMAILIT_API_KEY. |
Adicione EMAILIT_API_KEY ao bloco env da configuração do seu cliente. |
O cliente não consegue iniciar o npx |
Os apps de desktop nem sempre enxergam o PATH do seu shell. Use o caminho completo do npx (descubra-o com which npx) como command. |
Domain not verified ao enviar |
Use um remetente em um domínio verificado ou defina SENDER_EMAIL_ADDRESS com um endereço desse tipo. |
| Erros de permissão em ferramentas que não são de envio | A chave é Sending Only. Use uma chave Full Access para domínios, templates, contatos e outras ferramentas. |
| Um e-mail agendado não pode ser cancelado | Os e-mails agendados só podem ser cancelados ou reagendados até 3 minutos antes do horário de envio. |