# Run the MCP server locally

> Run the open-source @emailit/emailit-mcp package over stdio or local HTTP with an API key, and configure Claude, Cursor and VS Code to use it.

`@emailit/emailit-mcp` is the open-source version of the Emailit MCP server. It runs on your machine, talks to the Emailit API with your API key, and works with clients that only support local (stdio) servers. Most people should use the [hosted server](/docs/mcp/) instead; this page explains when the local package makes sense and how to configure it.

- **Package:** [`@emailit/emailit-mcp`](https://www.npmjs.com/package/@emailit/emailit-mcp) on npm
- **Source:** [github.com/emailit/emailit-mcp](https://github.com/emailit/emailit-mcp), MIT license
- **Runtime:** Node.js 18 or later

## Local or hosted

| | Local package | Hosted server |
| --- | --- | --- |
| Runs | On your machine, started by your MCP client | At `https://api.emailit.com/mcp` |
| Sign-in | API key only | OAuth or API key |
| Tools | The original set: emails, domains, API keys, audiences, contacts, templates, suppressions and webhooks | 109, the full API v2, including campaigns, automations, forms, DMARC, verification and events |
| Workspaces | The API key's workspace | Several workspaces per connection with OAuth, chosen per request |
| Roles and scopes | The API key's scope | Your role in each workspace and the approved scope |
| Default sender and reply-to | Configurable | Not available; the assistant passes `from` on each send |
| Updates | You control the version you run | Automatic |

Choose the local package when:

- your client only supports stdio servers, or can't do OAuth for remote servers,
- you want a default From and Reply-To address applied to every send, or
- you want to read, pin or modify the server code.

## Before you begin

- [Node.js](https://nodejs.org) 18 or later, so `npx` is available.
- An [API key](/docs/developers/api-keys/). Use a Sending Only key, restricted to one domain, if the assistant only needs to send; the other tools need Full Access.
- A [verified sending domain](/docs/domains/add-a-domain/) for the sender address.

## Configure your client

The client starts the server as a subprocess and talks to it over stdio. Pass the API key through the `EMAILIT_API_KEY` environment variable.

**Claude Code**

```bash
claude mcp add emailit \
  -e EMAILIT_API_KEY=secret_•••••••• \
  -e SENDER_EMAIL_ADDRESS=hello@acme.com \
  -- npx -y @emailit/emailit-mcp
```

**Claude Desktop**

  Open **Settings > Developer > Edit Config** and add the server to `claude_desktop_config.json`, then restart Claude Desktop:

```json title="claude_desktop_config.json"
{
  "mcpServers": {
    "emailit": {
      "command": "npx",
      "args": ["-y", "@emailit/emailit-mcp"],
      "env": {
        "EMAILIT_API_KEY": "secret_••••••••",
        "SENDER_EMAIL_ADDRESS": "hello@acme.com"
      }
    }
  }
}
```

**Cursor**

  Add the server to `~/.cursor/mcp.json` or a project's `.cursor/mcp.json`:

```json title="~/.cursor/mcp.json"
{
  "mcpServers": {
    "emailit": {
      "command": "npx",
      "args": ["-y", "@emailit/emailit-mcp"],
      "env": {
        "EMAILIT_API_KEY": "secret_••••••••",
        "SENDER_EMAIL_ADDRESS": "hello@acme.com"
      }
    }
  }
}
```

**VS Code**

  Add the server to `.vscode/mcp.json`. VS Code prompts for the key and stores it securely:

```json title=".vscode/mcp.json"
{
  "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"
      }
    }
  }
}
```

Always use the scoped package name, `@emailit/emailit-mcp`.

## Environment variables

| Variable | Required | Description |
| --- | --- | --- |
| `EMAILIT_API_KEY` | For stdio | Your Emailit API key. In HTTP mode, clients send their own key instead. |
| `SENDER_EMAIL_ADDRESS` | No | Default From address, on a verified sending domain. |
| `REPLY_TO_EMAIL_ADDRESSES` | No | Comma-separated default Reply-To addresses. |
| `MCP_PORT` | No | Port for HTTP mode. Defaults to `3000`. |

If you don't set a sender, the server asks the assistant for a From address on each send.

## Command-line flags

Flags override the matching environment variables.

| Flag | Description |
| --- | --- |
| `--key <key>` | API key for stdio mode. |
| `--sender ` | Default From address. |
| `--reply-to ` | Default Reply-To address. Repeat the flag for several addresses. |
| `--http` | Serve Streamable HTTP instead of stdio. |
| `--port ` | Port for `--http`. Defaults to `3000` or `MCP_PORT`. |
| `-h`, `--help` | Print usage. |

## Run over HTTP

To share one local server between several clients, start it in HTTP mode:

```bash
npx -y @emailit/emailit-mcp --http --port 3000
```

The server listens on `http://127.0.0.1:3000/mcp` and is only reachable from your machine. Each client authenticates with its own API key as a bearer token:

```bash
claude mcp add emailit --transport http http://127.0.0.1:3000/mcp \
  --header "Authorization: Bearer $EMAILIT_API_KEY"
```

## Run from source

```bash
git clone https://github.com/emailit/emailit-mcp.git
cd emailit-mcp
npm install
EMAILIT_API_KEY=secret_•••••••• node src/index.js
```

Add `--http --port 3000` to the last command for HTTP mode.

## Troubleshooting

| Problem | Fix |
| --- | --- |
| `API key is required for stdio mode. Use --key or set EMAILIT_API_KEY.` | Add `EMAILIT_API_KEY` to the `env` block of your client configuration. |
| The client can't start `npx` | Desktop apps don't always see your shell's `PATH`. Use the full path to `npx` (find it with `which npx`) as the `command`. |
| `Domain not verified` when sending | Use a sender on a [verified domain](/docs/domains/verification/), or set `SENDER_EMAIL_ADDRESS` to one. |
| Permission errors on non-send tools | The key is Sending Only. Use a Full Access key for domains, templates, contacts and other tools. |
| A scheduled email can't be canceled | Scheduled emails can only be canceled or rescheduled up to 3 minutes before their send time. |

## Related

  - [MCP server overview](/docs/mcp/): Hosted vs local, scopes and security.
  - [Tool reference](/docs/mcp/tools/): Every hosted tool and its arguments.
  - [API keys](/docs/developers/api-keys/): Create a key for the server.
  - [Other clients](/docs/mcp/other-clients/): Connect editors to the hosted server.

---
Source: https://emailit.com/docs/mcp/local-server/