# MCP Server

> Use the MailBlastr MCP server to give your AI agent native access to the full MailBlastr platform over natural language.

## What is an MCP server?

MCP (Model Context Protocol) is an open protocol that standardizes how applications provide context to LLMs. Among other benefits, it gives LLMs tools to act on your behalf.

## What can the MailBlastr MCP server do?

The MailBlastr MCP server gives your AI agent native access to the full MailBlastr platform through a single integration. You can manage your email infrastructure using natural language:

- **Emails** — send, list, get, cancel, update, and batch-send emails. Supports HTML, plain text, attachments (local file, URL, or base64), CC/BCC, reply-to, scheduling, tags, and topic-based sending.
- **Received emails** — list and read inbound emails; list and download received attachments.
- **Contacts** — create, list, get, update, and remove contacts. Manage segment memberships, topic subscriptions, and CSV imports, with custom contact properties.
- **Campaigns** — create, send, list, get, update, and remove campaigns, with scheduling, personalization placeholders, and preview text.
- **Domains** — create, list, get, update, remove, and verify sender domains. Configure tracking, TLS, and sending/receiving capabilities.
- **Segments** — create, list, get, and remove audience segments.
- **Topics** — create, list, get, update, and remove subscription topics.
- **Contact properties** — create, list, get, update, and remove custom contact attributes.
- **API keys** — create, list, and remove API keys.
- **Webhooks** — create, list, get, update, and remove webhooks for event notifications.

> **Note:** The server also includes `create-contact-import`, `get-contact-import`, and `list-contact-imports` tools to upload CSV files, check import status, and review previous imports.

## Prerequisites

The MailBlastr MCP server is published on NPM as `mailblastr-mcp` and runs with `npx` in any supported MCP client. Before you start:

- [Create an API key](https://www.mailblastr.com/docs/api-keys/overview).
- [Verify your domain](https://www.mailblastr.com/docs/domains/managing).

## Stdio transport (default)

The server supports two transport modes: **stdio** (default) and **HTTP**. Replace `mb_xxxxxxxxx` with your actual key in every example below.

**Claude Code**

```bash
claude mcp add mailblastr -e MAILBLASTR_API_KEY=mb_xxxxxxxxx -- npx -y mailblastr-mcp
```

**Codex**

```bash
codex mcp add mailblastr \
  --env MAILBLASTR_API_KEY=mb_xxxxxxxxx \
  -- npx -y mailblastr-mcp
```

**Cursor**

```json
{
  "mcpServers": {
    "mailblastr": {
      "command": "npx",
      "args": ["-y", "mailblastr-mcp"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Claude Desktop**

```json
{
  "mcpServers": {
    "mailblastr": {
      "command": "npx",
      "args": ["-y", "mailblastr-mcp"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Windsurf**

```json
{
  "mcpServers": {
    "mailblastr": {
      "command": "npx",
      "args": ["-y", "mailblastr-mcp"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**Copilot**

```json
// Add to your VS Code settings.json:
{
  "mcp": {
    "servers": {
      "mailblastr": {
        "command": "npx",
        "args": ["-y", "mailblastr-mcp"],
        "env": {
          "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
        }
      }
    }
  }
}
```

**Gemini CLI**

```json
{
  "mcpServers": {
    "mailblastr": {
      "command": "npx",
      "args": ["-y", "mailblastr-mcp"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**OpenCode**

```json
// Add to your opencode.json config:
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mailblastr": {
      "type": "local",
      "command": ["npx", "-y", "mailblastr-mcp"],
      "enabled": true,
      "environment": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

## HTTP transport

Run the server over HTTP for remote or web-based integrations. In HTTP mode, each client authenticates by passing its MailBlastr API key as a Bearer token in the `Authorization` header.

**Start the server**

```bash
npx -y mailblastr-mcp --http --port 3000
```

The server listens on `http://127.0.0.1:3000` and exposes the MCP endpoint at `/mcp` using Streamable HTTP.

**Claude Code**

```bash
claude mcp add mailblastr --transport http http://127.0.0.1:3000/mcp --header "Authorization: Bearer mb_xxxxxxxxx"
```

**Cursor**

```json
{
  "mcpServers": {
    "mailblastr": {
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer mb_xxxxxxxxx"
      }
    }
  }
}
```

You can also set the port via the `MCP_PORT` environment variable: `MCP_PORT=3000 npx -y mailblastr-mcp --http`.

## Options

Pass additional arguments to configure the server:

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `--key` | string | No | Your MailBlastr API key (stdio mode only — HTTP mode uses the client Bearer token). |
| `--sender` | string | No | Default sender email address from a verified domain. |
| `--reply-to` | string | No | Default reply-to address (can be specified multiple times). |
| `--http` | flag | No | Use HTTP transport instead of stdio (default: stdio). |
| `--port` | number | No | HTTP port when using `--http` (default: 3000, or `MCP_PORT`). |

### Environment variables

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `MAILBLASTR_API_KEY` | string | No | Your API key. Required for stdio; optional for HTTP since clients pass it via Bearer token. |
| `SENDER_EMAIL_ADDRESS` | string | No | Default sender address from a verified domain (optional). |
| `REPLY_TO_EMAIL_ADDRESSES` | string | No | Comma-separated reply-to addresses (optional). |
| `MCP_PORT` | number | No | HTTP port when using `--http` (optional). |

> **Note:** If you do not provide a sender email address, the MCP server asks you to provide one each time you call a send tool.

## Local development

To run from a local build instead of `npx`, clone and build the project, then point your client at the built entry file.

**Clone and build**

```bash
git clone https://github.com/mailblastr/mailblastr-mcp.git
pnpm install
pnpm run build
```

Then replace the `npx` command with the path to your local build:

**Claude Code (stdio)**

```bash
claude mcp add mailblastr -e MAILBLASTR_API_KEY=mb_xxxxxxxxx -- node ABSOLUTE_PATH_TO_PROJECT/dist/index.js
```

**Cursor (stdio)**

```json
{
  "mcpServers": {
    "mailblastr": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_PROJECT/dist/index.js"],
      "env": {
        "MAILBLASTR_API_KEY": "mb_xxxxxxxxx"
      }
    }
  }
}
```

**HTTP**

```bash
node ABSOLUTE_PATH_TO_PROJECT/dist/index.js --http --port 3000
```

### Testing with MCP Inspector

After building, start the inspector to verify the server and list its tools:

```bash
export MAILBLASTR_API_KEY=mb_your_key_here
pnpm inspector
```

- **Stdio** — choose *stdio (launch a process)*, set **Command** to `node`, **Args** to `dist/index.js`, and **Env** to `MAILBLASTR_API_KEY=mb_your_key_here`. Click **Connect**, then **List tools**.
- **HTTP** — start the server with `node dist/index.js --http --port 3000`, then in the inspector choose *Streamable HTTP*, set **URL** to `http://127.0.0.1:3000/mcp`, add header `Authorization: Bearer mb_your_key_here`, and click **Connect**.