Ballast

Ballast MCP Server

Official Model Context Protocol (MCP) server implementation for [Ballast](https://ballast.to) — 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](https://ballast.to/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