Ballast MCP Server

Ballast MCP Server

Official Model Context Protocol (MCP) server implementation for Ballast — connect AI agents to manage cold email campaigns, deliverability warmup, lead lists, and inbox replies.

This repository contains the standalone MCP server package that runs locally via standard I/O (stdio) and connects AI assistants (Claude Desktop, Cursor, Claude Code, Zed, etc.) to your Ballast workspace.

---

Features

• Deliverability & DNS Diagnostics: Inspect secondary domains for SPF, DKIM, DMARC alignment, MX configuration, and blacklist health.
• Campaign & Sequence Management: Build multi-step outbound sequences, set A/B variants, configure sending delays, and verify launch checklists.
• Automated Bounce Circuit Breakers: Monitor campaign placement rates and pause sends if bounce rate thresholds are crossed.
• Unified Inbox (Unibox): Read and summarize customer email threads, check sentiment classification, and draft human-confirmed replies.
• Safe by Default: Destructive operations (launching campaigns, sending emails, deleting data) require explicit two-step confirmation with a 10-minute HMAC token.

---

Installation & Setup

Requirements

• Node.js >= 18.0.0
• A Ballast workspace API key from Settings > API Keys (starts with bl_).

Run via npx (Recommended)

You can run the server directly without manual installation:

BALLAST_API_KEY="bl_your_key_here" npx -y ballast-mcp

Install from Source

git clone https://github.com/useballast/ballast-mcp.git
cd ballast-mcp
npm install
npm start

---

Client Configuration

Claude Desktop

Add Ballast to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": ["-y", "ballast-mcp"],
      "env": {
        "BALLAST_API_KEY": "bl_your_api_key_here"
      }
    }
  }
}

---

Cursor

Add to ~/.cursor/mcp.json (or your project's .cursor/mcp.json):

{
  "mcpServers": {
    "ballast": {
      "command": "npx",
      "args": ["-y", "ballast-mcp"],
      "env": {
        "BALLAST_API_KEY": "bl_your_api_key_here"
      }
    }
  }
}

---

Claude Code

claude mcp add --transport stdio ballast -- npx -y ballast-mcp --key=bl_your_api_key_here

(Note: For clients that support remote Streamable HTTP directly, you can also use --transport http ballast https://ballast.to/api/mcp --header "Authorization: Bearer bl_...")

---

Tools Reference

The server implements 30 core tools organized by functional area:

---

Safety: Two-Step Confirmations

To prevent inadvertent mass sends or data deletion:

1. When calling launch_campaign, send_reply, or deletion tools without a confirm_token, the server generates a dry-run preview describing the exact outcome (e.g. "Will send 320 emails across 6 mailboxes") and issues an HMAC token.
2. The AI presents the preview to the user.
3. The action executes only when the user approves and the AI passes the confirm_token.

---

Development

git clone https://github.com/useballast/ballast-mcp.git
cd ballast-mcp
npm install
npm test # or npm start

License

MIT © Ballast