# Breaker MCP server and API

Source: https://joinbreaker.ai/mcp

**Connect any AI model to your newsletter.** Breaker ships with an MCP server and a full REST API. Your model drafts campaigns, builds segments, and pulls the numbers; you review the work and press send.

- API docs: https://docs.breaker.email
- npm package: https://www.npmjs.com/package/@breaker-email/mcp
- Hosted MCP endpoint (web clients, OAuth sign-in): `https://api.breaker.email/mcp`

## One API, every part of your account

- **Campaigns**: create and update draft campaigns, read and replace the body, render a preview. Drafts open in the editor, ready to edit by hand.
- **Reporting**: opens, clicks, unsubscribes, and RealClick for one campaign or an aggregated time period.
- **Segments**: static lists or rule-driven dynamic segments. Create them, read and replace the rules, list members, recalculate.
- **Contacts**: create, find, update and tag contacts, change subscription status, pull per-contact engagement. List tags, custom fields and signup forms.

## How it works

MCP is an open standard that lets a model use outside tools. Breaker's MCP server hands your model the controls: campaigns, segments, contacts, and reports. Ask in plain English and get answers from your live account data.

1. **Connect.** Add Breaker to claude.ai with one URL, or to Claude Code, Cursor, Codex and any other MCP client.
2. **Ask.** Draft content, build segments, question your stats.
3. **Review.** Open the draft in your editor, change what you want, send it.

Example: "Which subject lines beat 60% opens this quarter?" runs `report_summary(from="2026-07-01", to="2026-09-30")` and answers with the campaigns above 60%. "Tag everyone who clicked the webinar link as warm" runs `contact_tag(tag="warm")` for each contact.

## Guardrails

- **No send access.** Models and API keys cannot send a campaign or delete contacts. Only you can do that.
- **Drafts open in your editor.** Everything the model writes lands in the campaign editor, editable before it goes out.
- **You approve every send.** A person reads the issue and presses the button.

## Install

### Hosted endpoint: claude.ai and Claude Desktop

Nothing to install and no API key. In claude.ai (or Claude Desktop) open **Settings**, **Connectors**, **Add custom connector**. Name it **Breaker**, paste `https://api.breaker.email/mcp`, click **Add**, then **Connect** and sign in with your Breaker account. The sign-in picks the one newsletter this connection can reach. The connection is listed, and can be removed, in Breaker under **Settings**, **Integrations**, **AI Clients**. Run more than one newsletter? Add the connector once per newsletter.

### Hosted endpoint: ChatGPT

ChatGPT connects to the hosted endpoint as an MCP app through Developer mode (a beta feature on Plus and Pro; on Business, Enterprise and Edu an admin has to enable it). Open **Settings**, **Plugins**, **Developer mode** and enable it. Go to **Settings**, **Plugins**, **Browse Plugins**, press **+** and select **Create MCP App**. Name the connection, paste `https://api.breaker.email/mcp` under **Connection**, leave authentication as **OAuth**, and sign in with your Breaker account when asked.

### Local server: Claude Code, Codex, Cursor, VS Code, Windsurf and other stdio clients

Needs an API key from **Settings**, **API Keys** in the Breaker app (keys look like `bk_live_...`; one key belongs to one newsletter).

Claude Code, at user scope so every project sees it:

```
claude mcp add breaker --scope user --env BREAKER_API_KEY=bk_live_your_key_here -- npx -y -p @breaker-email/mcp breaker-mcp
```

Codex:

```
codex mcp add breaker --env BREAKER_API_KEY=bk_live_your_key_here -- npx -y -p @breaker-email/mcp breaker-mcp
```

Any other client, in its MCP config file (VS Code uses the same shape under a `servers` key instead of `mcpServers`; Codex stores the equivalent as TOML under `[mcp_servers.breaker]`):

```json
{
  "mcpServers": {
    "breaker": {
      "command": "npx",
      "args": ["-y", "-p", "@breaker-email/mcp", "breaker-mcp"],
      "env": { "BREAKER_API_KEY": "bk_live_your_key_here" }
    }
  }
}
```

Keep the `-p` flag and the `breaker-mcp` binary name exactly as written: npx is told the package and the executable separately. `BREAKER_API_KEY` in the env block is the correct mechanism for a stdio server, not a workaround.

### Setup prompt for an AI coding assistant

Paste this into Claude Code, Codex, Cursor, or any AI coding assistant. It asks for your key, works out which client it is running in, registers the server, and checks the connection.

```
Set up the Breaker MCP server for me.

Breaker is an email newsletter platform. For this setup the MCP server runs
locally over stdio via npx and authenticates with an API key — do not look for
a browser sign-in or a hosted endpoint.

1. Ask me for my Breaker API key before you write any config. It looks like
   bk_live_... . If I don't have one, tell me to create it at
   https://app.breaker.email under Settings then API Keys, and wait for me. You
   cannot create a key yourself.

2. Work out which MCP client you are running in and register the server using
   that client's own method, named "breaker", at user scope where the client
   has one (Claude Code: `claude mcp add breaker --scope user --env
   BREAKER_API_KEY=... -- npx -y -p @breaker-email/mcp breaker-mcp`; Codex:
   `codex mcp add breaker --env BREAKER_API_KEY=... -- npx -y -p
   @breaker-email/mcp breaker-mcp`; any other client: add a "breaker" entry with
   command "npx", args ["-y", "-p", "@breaker-email/mcp", "breaker-mcp"] and
   env BREAKER_API_KEY to its MCP config file; VS Code uses a "servers" key
   rather than "mcpServers"). Keep the -p flag and the breaker-mcp binary name
   exactly as written.

3. Confirm it worked before calling it done. Check the breaker tools are listed,
   then call newsletter_get, which takes no arguments and only reads. Tell me
   which newsletter it returned. A 401 means the key is wrong or revoked — tell
   me, don't retry. During setup, never call a tool that creates, updates or
   deletes anything.

4. A Breaker API key belongs to one newsletter. Once you know the name, offer to
   rename the server to breaker-<newsletter> (lowercase, spaces and punctuation
   replaced with dashes). Only rename if I say yes, and do it by removing and
   re-adding the server with the same key.
```

## The 35 tools

The same tools whether you use the hosted endpoint or run the server yourself. The server is a thin client of the public REST API: it holds no data and adds no behaviour of its own. Anything the API refuses, it refuses too.

- **Newsletter**: read which newsletter the API key belongs to.
- **Campaigns**: list and read campaigns, create a draft, change its title, subject and preview text, read and replace its body, preview the rendered email. The write tool spells out the markup the Breaker editor adopts as real blocks: columns, buttons, images, dividers and merge tags.
- **Reports**: newsletter and per-campaign totals over a date window, per-contact engagement, links and who clicked them, subscriber count and unsubscribes.
- **Segments**: list and read segments, create one from a fixed list of contacts or from rules, read and replace a dynamic segment's rules, add contacts to a static one, recalculate a dynamic one.
- **Contacts**: create, find, read and update contacts, add and remove tags, read status and per-campaign engagement, list tags, custom fields and signup forms.