DocumentationAPI ReferenceKnowledge Base
AI Tools

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.
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:

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 mcp add mailblastr -e MAILBLASTR_API_KEY=mb_xxxxxxxxx -- npx -y mailblastr-mcp

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
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 mcp add mailblastr --transport http http://127.0.0.1:3000/mcp --header "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:

--keystringoptional

Your MailBlastr API key (stdio mode only — HTTP mode uses the client Bearer token).

--senderstringoptional

Default sender email address from a verified domain.

--reply-tostringoptional

Default reply-to address (can be specified multiple times).

--httpflagoptional

Use HTTP transport instead of stdio (default: stdio).

--portnumberoptional

HTTP port when using --http (default: 3000, or MCP_PORT).

Environment variables

MAILBLASTR_API_KEYstringoptional

Your API key. Required for stdio; optional for HTTP since clients pass it via Bearer token.

SENDER_EMAIL_ADDRESSstringoptional

Default sender address from a verified domain (optional).

REPLY_TO_EMAIL_ADDRESSESstringoptional

Comma-separated reply-to addresses (optional).

MCP_PORTnumberoptional

HTTP port when using --http (optional).

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
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 mcp add mailblastr -e MAILBLASTR_API_KEY=mb_xxxxxxxxx -- node ABSOLUTE_PATH_TO_PROJECT/dist/index.js

Testing with MCP Inspector

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

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.