Ballast

Ballast MCP サーバー

Ballast の公式 Model Context Protocol (MCP) サーバー実装です。AI エージェントを接続して、コールドメールキャンペーン、配信到達率のウォームアップ、リードリスト、受信トレイの返信を管理できます。

このリポジトリには、標準入出力（stdio）を介してローカルで実行されるスタンドアロンの MCP サーバーパッケージが含まれており、AI アシスタント（Claude Desktop、Cursor、Claude Code、Zed など）を Ballast ワークスペースに接続します。

---

機能

• 配信到達率と DNS の診断：セカンダリドメインの SPF、DKIM、DMARC の整合性、MX 設定、ブラックリストの状態を確認します。
• キャンペーンとシーケンスの管理：複数ステップのアウトバウンドシーケンスを作成し、A/B バリエーションを設定し、送信間隔を調整して、開始前のチェックリストを確認します。
• 自動バウンス遮断機能：キャンペーンの配置率を監視し、バウンス率がしきい値を超えた場合に送信を一時停止します。
• 統合受信トレイ（Unibox）：顧客とのメールスレッドを読み取って要約し、センチメント分類を確認して、人による確認を経て返信を作成します。
• デフォルトで安全：キャンペーンの開始、メールの送信、データの削除など、破壊的な操作には、10 分間有効な HMAC トークンを使った明示的な 2 段階の確認が必要です。

---

インストールとセットアップ

要件

• Node.js >= 18.0.0
• Settings > API Keys で取得した Ballast ワークスペースの API キー（bl_ で始まります）。

npx で実行（推奨）

手動でインストールせずに、サーバーを直接実行できます。

BALLAST_API_KEY="bl_your_key_here" npx -y ballast-mcp

ソースからインストール

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

---

クライアントの設定

Claude Desktop

claude_desktop_config.json に Ballast を追加します。

• 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

~/.cursor/mcp.json（またはプロジェクトの .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

（注：リモートの Streamable HTTP を直接サポートするクライアントでは、--transport http ballast https://ballast.to/api/mcp --header "Authorization: Bearer bl_..." も使用できます。）

---

ツールリファレンス

サーバーには、機能領域ごとに分類された30のコアツールが実装されています。

ツール	カテゴリー	説明
whoami	ワークスペース	認証済みユーザー、アクティブなワークスペース、権限ロールを取得します。
get_overview	ワークスペース	すべてのキャンペーンにわたるワークスペース全体の集計値と推移（送信数、返信数、センチメント、バウンス数）を取得します。
get_billing	ワークスペース	プランの詳細、送信枠、専用 IP、使用制限を取得します。
check_domain	ドメイン	ドメインを追加せずに、任意のドメインの DNS と到達性をリアルタイムで診断します。
list_domains	ドメイン	到達性スコアと認証状況を含む、接続済みの送信ドメインを一覧表示します。
add_domain	ドメイン	新しい送信ドメインをワークスペースに接続して登録します。
list_mailboxes	メールボックス	1日あたりの上限を含む、接続済みの Google Workspace および Microsoft 365 のメールボックスを一覧表示します。
add_mailbox	メールボックス	アウトバウンドの営業メール送信用に外部メールボックスを接続します。
list_leads	リード	ワークスペース内の連絡先を検索、絞り込みします。
import_leads	リード	カスタム変数とタグの割り当てを指定して、リードの連絡先をインポートします。
list_lead_lists	リード	整理されたリードセグメントとメンバー数を一覧表示します。
add_suppressions	リード	ワークスペース全体の連絡禁止リストに、メールアドレスまたはルートドメインを追加します。
list_campaigns	キャンペーン	送信スケジュールとステータスを含む、アウトバウンドシーケンスを一覧表示します。
create_campaign	キャンペーン	新しいコールドメールキャンペーンを作成します。
get_campaign	キャンペーン	キャンペーンの設定、ステップのバリエーション、割り当てられたメールボックスを取得します。
update_campaign	キャンペーン	キャンペーンのスケジュール、1日の送信上限、またはトラッキング設定を更新します。
set_sequence	キャンペーン	シーケンスのステップ、遅延時間、件名、本文を設定します。
write_sequence	キャンペーン	AI を使って複数ステップのシーケンス本文を生成、または推敲します。
add_leads_to_campaign	キャンペーン	リードセグメントをアクティブなシーケンスに登録します。
preview_campaign	キャンペーン	メールボックスごとのリードへの送信分布と初回送信時刻をプレビューします。
get_launch_checklist	キャンペーン	キャンペーン開始前に、ドメインの整合性、送信者のウォームアップ、リードの健全性を確認します。
launch_campaign	キャンペーン	シーケンスの送信を開始します（確認トークンが必要です）。
pause_campaign	キャンペーン	キャンペーンの送信をただちに一時停止します。
get_campaign_stats	キャンペーン	キャンペーン単体または全キャンペーンの、日ごとの時系列メール指標を取得します。
get_campaign_analytics	キャンペーン	メールプロバイダー（Google、Microsoft）、メールボックス、センチメントごとに、詳細なパフォーマンスの内訳を取得します。
get_unibox_filters	Unibox	統合受信トレイのフィルタープリセットとラベル数を取得します。
list_threads	Unibox	受信した宛先からの返信と会話スレッドを一覧表示します。
get_thread	Unibox	スレッド内の全メッセージ履歴、ヘッダー、リードの詳細を確認します。
send_reply	Unibox	スレッドに割り当てられたメールボックスからメールの返信を送信します（確認トークンが必要です）。
label_thread	Unibox	センチメントラベル（興味あり、ミーティング予約済み、興味なし、不在）を適用します。

---

安全性：2段階の確認

意図しない一斉送信やデータ削除を防ぐため、次の手順を実行します。

1. confirm_token を指定せずに launch_campaign、send_reply、または削除ツールを呼び出すと、サーバーは正確な実行結果（例：「6つのメールボックスから320通のメールを送信します」）を示すドライランのプレビューを生成し、HMAC トークンを発行します。
2. AI がプレビューをユーザーに提示します。
3. ユーザーが承認し、AI が confirm_token を渡した場合にのみ、アクションが実行されます。

---

開発

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

ライセンス

MIT © Ballast