Ballast

io.github.useballastPublished by GitHub account useballastv1.0.2Updated Oct 30, 2026

Cold email outreach: manage campaigns, lead sequences, mailbox warmup, and unified inbox replies.

VerifiedStreamable HTTPWeb executableCommunication & CollaborationBusiness & Commerce

Overview

AI-generated overview

Ballast connects an AI assistant to a cold email outreach workspace to manage campaigns, sequences, lead lists, mailbox warmup and inbox replies.

What you can do
  • Inspect workspace identity, aggregate performance, billing plan and sending limits
  • Check domains and mailboxes: DNS and deliverability diagnostics, list or add sending domains and connected mailboxes
  • Manage leads: search, import, list segments, and add do-not-contact suppressions
  • Build and run campaigns: create, update, set sequences, enroll leads, preview distribution, check launch readiness, launch or pause, and read stats and analytics
  • Handle the unified inbox: list and read threads, draft and send replies, apply sentiment labels
When to use it
Useful when you run cold email outreach in Ballast and want an assistant to draft sequences, audit domain and mailbox deliverability, review campaign metrics, or triage and answer replies without switching to the web app.
Requirements
A Ballast workspace account and an API key from Settings > API Keys (passed as BALLAST_API_KEY for the local npm package), or OAuth for the hosted remote endpoint. The local package needs Node.js 18 or newer; the remote endpoint needs network access.
Before you install
The server can send real email and change outreach data: launching campaigns, sending replies and deletions require a two-step confirmation token, so review the dry-run preview before approving. It handles lead contact data and mailbox connections, and the API key grants access to the whole workspace, so store it carefully.

Installation

In SourceWeft

  1. Open Ballast in the dashboard and add it to a workspace.
  2. Connect the required credentials. They are stored privately and never shown on public pages.
  3. Enable the server for the chats that should use its tools.

Web executable via Streamable HTTP. Remote servers run from the web runtime once configured in a workspace.

Use with an agent

Paste this prompt into Claude Code, Codex, Cursor or another agent — or into SourceWeft chat. The agent reads this server's install guide, shows you its publisher, endpoint and sign-in, and adds it to your client once you agree. Keys never go into a command.

Read https://sourceweft.com/mcp/io.github.useballast%2Fballast-mcp/install.md and connect the MCP server it describes to my client. Before changing any config, show me its publisher, endpoint and sign-in method and wait for my OK. Never put an API key in a command or in a file I would commit; ask me where it should come from.

Read the install guide the agent follows

Other MCP clients

Add this to your client's mcpServers config. The client completes OAuth sign-in on first connect.

{
  "mcpServers": {
    "ballast": {
      "type": "http",
      "url": "https://ballast.to/api/mcp"
    }
  }
}

README

Ballast MCP Server

[Ballast - Cold Email MCP server – quality and maintenance score on Glama] [Protocol] [License: MIT]

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

Run via npx (Recommended)

You can run the server directly without manual installation:

bash
BALLAST_API_KEY="bl_your_key_here" npx -y ballast-mcp

Install from Source

bash
git clone https://github.com/useballast/ballast-mcp.gitcd ballast-mcpnpm installnpm 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
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):

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

Claude Code

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

ToolCategoryDescription
whoamiWorkspaceGet authenticated user, active workspace, and permission role.
get_overviewWorkspaceWorkspace-wide aggregate totals and trends across all campaigns (sends, replies, sentiment, bounces).
get_billingWorkspacePlan details, sending allowances, dedicated IPs, and usage limits.
check_domainDomainsLive DNS & deliverability diagnostics on any domain without adding it.
list_domainsDomainsList connected sending domains with deliverability scores and verification status.
add_domainDomainsConnect and register a new sending domain to the workspace.
list_mailboxesMailboxesList connected Google Workspace and Microsoft 365 mailboxes with daily limits.
add_mailboxMailboxesConnect an external mailbox for outbound outreach.
list_leadsLeadsSearch and filter contacts in your workspace.
import_leadsLeadsImport lead contacts with custom variables and tag assignment.
list_lead_listsLeadsList organized lead segments and member counts.
add_suppressionsLeadsAdd email addresses or root domains to workspace-wide do-not-contact lists.
list_campaignsCampaignsList outbound sequences with sending schedules and statuses.
create_campaignCampaignsCreate a new cold email campaign.
get_campaignCampaignsRetrieve campaign settings, step variants, and assigned mailboxes.
update_campaignCampaignsUpdate campaign schedule, daily quotas, or track settings.
set_sequenceCampaignsConfigure sequence steps, delays, subject lines, and body copy.
write_sequenceCampaignsGenerate or polish multi-step sequence copy using AI.
add_leads_to_campaignCampaignsEnroll lead segments into an active sequence.
preview_campaignCampaignsPreview lead send distribution across mailboxes and first send timings.
get_launch_checklistCampaignsCheck domain alignment, sender warmup, and lead hygiene before launch.
launch_campaignCampaignsLaunch sequence sending (requires confirm token).
pause_campaignCampaignsImmediately pause sending for a campaign.
get_campaign_statsCampaignsDaily time-series email metrics for a campaign or all campaigns over time.
get_campaign_analyticsCampaignsGranular performance breakdown across email providers (Google, Microsoft), mailboxes, and sentiment.
get_unibox_filtersUniboxRetrieve unified inbox filter presets and label counts.
list_threadsUniboxList incoming recipient replies and conversation threads.
get_threadUniboxInspect full thread message history, headers, and lead details.
send_replyUniboxSend an email reply from the thread's assigned mailbox (requires confirm token).
label_threadUniboxApply sentiment labels (Interested, Meeting Booked, Not Interested, Out of Office).

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

bash
git clone https://github.com/useballast/ballast-mcp.gitcd ballast-mcpnpm installnpm test # or npm start

License

MIT © Ballast

Source: README.md at commit e8fbd4f

Tools

0
This server asks you to sign in, so SourceWeft could not read its tools without an account and has not indexed them. What a connected account sees can depend on that account and its permissions.

Version history

1
  1. v1.0.2LatestOct 30, 2026

Score

85% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 daysRequired25 pts
  • Auth declaredRequired10 pts
  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts