Guida pratica
Esegui il server MCP in locale
Esegui il pacchetto open source @emailit/emailit-mcp via stdio o HTTP locale con una chiave API, e configura Claude, Cursor e VS Code per usarlo.
@emailit/emailit-mcp è la versione open source del server MCP di Emailit. Gira sulla tua macchina, comunica con l’API di Emailit usando la tua chiave API e funziona con i client che supportano solo server locali (stdio). Nella maggior parte dei casi conviene usare il server ospitato; questa pagina spiega quando ha senso il pacchetto locale e come configurarlo.
- Pacchetto:
@emailit/emailit-mcpsu npm - Sorgente: github.com/emailit/emailit-mcp, licenza MIT
- Runtime: Node.js 18 o versioni successive
Locale od ospitato
| Pacchetto locale | Server ospitato | |
|---|---|---|
| Dove gira | Sulla tua macchina, avviato dal client MCP | Su https://api.emailit.com/mcp |
| Accesso | Solo chiave API | OAuth o chiave API |
| Strumenti | Il set originale: email, domini, chiavi API, liste, contatti, template, soppressioni e webhook | 109, l’intera API v2, comprese campagne, automazioni, moduli, DMARC, verifica ed eventi |
| Workspace | Il workspace della chiave API | Più workspace per connessione con OAuth, scelti per ogni richiesta |
| Ruoli e permessi | Il permesso (scope) della chiave API | Il tuo ruolo in ciascun workspace e il permesso approvato |
| Mittente e Reply-To predefiniti | Configurabili | Non disponibili; l’assistente passa from a ogni invio |
| Aggiornamenti | Scegli tu la versione da eseguire | Automatici |
Scegli il pacchetto locale quando:
- il tuo client supporta solo server stdio, o non può usare OAuth per i server remoti,
- vuoi un indirizzo From e Reply-To predefinito applicato a ogni invio, oppure
- vuoi leggere, bloccare a una versione o modificare il codice del server.
Prima di iniziare
- Node.js 18 o versioni successive, così
npxè disponibile. - Una chiave API. Usa una chiave di solo invio, limitata a un dominio, se l’assistente deve solo inviare; gli altri strumenti richiedono una chiave con accesso completo.
- Un dominio di invio verificato per l’indirizzo del mittente.
Configura il client
Il client avvia il server come sottoprocesso e comunica con esso via stdio. Passa la chiave API tramite la variabile d’ambiente EMAILIT_API_KEY.
claude mcp add emailit \
-e EMAILIT_API_KEY=secret_•••••••• \
-e SENDER_EMAIL_ADDRESS=hello@acme.com \
-- npx -y @emailit/emailit-mcpApri Settings > Developer > Edit Config e aggiungi il server a claude_desktop_config.json, poi riavvia Claude Desktop:
{
"mcpServers": {
"emailit": {
"command": "npx",
"args": ["-y", "@emailit/emailit-mcp"],
"env": {
"EMAILIT_API_KEY": "secret_••••••••",
"SENDER_EMAIL_ADDRESS": "hello@acme.com"
}
}
}
}Aggiungi il server a ~/.cursor/mcp.json o al file .cursor/mcp.json di un progetto:
{
"mcpServers": {
"emailit": {
"command": "npx",
"args": ["-y", "@emailit/emailit-mcp"],
"env": {
"EMAILIT_API_KEY": "secret_••••••••",
"SENDER_EMAIL_ADDRESS": "hello@acme.com"
}
}
}
}Aggiungi il server a .vscode/mcp.json. VS Code ti chiede la chiave e la salva in modo sicuro:
{
"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"
}
}
}
}Usa sempre il nome del pacchetto con scope, @emailit/emailit-mcp.
Variabili d’ambiente
| Variabile | Obbligatoria | Descrizione |
|---|---|---|
EMAILIT_API_KEY |
Per stdio | La tua chiave API di Emailit. In modalità HTTP, ogni client invia invece la propria chiave. |
SENDER_EMAIL_ADDRESS |
No | Indirizzo From predefinito, di un dominio di invio verificato. |
REPLY_TO_EMAIL_ADDRESSES |
No | Indirizzi Reply-To predefiniti, separati da virgole. |
MCP_PORT |
No | Porta per la modalità HTTP. Il valore predefinito è 3000. |
Se non imposti un mittente, il server chiede all’assistente un indirizzo From a ogni invio.
Flag della riga di comando
I flag sovrascrivono le variabili d’ambiente corrispondenti.
| Flag | Descrizione |
|---|---|
--key <key> |
Chiave API per la modalità stdio. |
--sender <email> |
Indirizzo From predefinito. |
--reply-to <email> |
Indirizzo Reply-To predefinito. Ripeti il flag per più indirizzi. |
--http |
Usa Streamable HTTP invece di stdio. |
--port <port> |
Porta per --http. Il valore predefinito è 3000 o MCP_PORT. |
-h, --help |
Mostra le istruzioni d’uso. |
Esegui via HTTP
Per condividere un unico server locale tra più client, avvialo in modalità HTTP:
npx -y @emailit/emailit-mcp --http --port 3000Il server è in ascolto su http://127.0.0.1:3000/mcp ed è raggiungibile solo dalla tua macchina. Ogni client si autentica con la propria chiave API come token Bearer:
claude mcp add emailit --transport http http://127.0.0.1:3000/mcp \
--header "Authorization: Bearer $EMAILIT_API_KEY"Esegui dal sorgente
git clone https://github.com/emailit/emailit-mcp.git
cd emailit-mcp
npm install
EMAILIT_API_KEY=secret_•••••••• node src/index.jsPer la modalità HTTP, aggiungi --http --port 3000 all’ultimo comando.
Risoluzione dei problemi
| Problema | Soluzione |
|---|---|
API key is required for stdio mode. Use --key or set EMAILIT_API_KEY. |
Aggiungi EMAILIT_API_KEY al blocco env della configurazione del client. |
Il client non riesce ad avviare npx |
Le app desktop non sempre vedono il PATH della shell. Usa come command il percorso completo di npx (lo trovi con which npx). |
Domain not verified durante l’invio |
Usa un mittente di un dominio verificato, oppure imposta SENDER_EMAIL_ADDRESS su un indirizzo di quel tipo. |
| Errori di permesso sugli strumenti diversi dall’invio | La chiave è di solo invio. Per domini, template, contatti e gli altri strumenti usa una chiave con accesso completo. |
| Un’email programmata non si può annullare | Le email programmate si possono annullare o riprogrammare solo fino a 3 minuti prima dell’orario di invio. |