@coldbirds/mcp-server

Control your ColdBirds Sequence cold-email workspace from any AI assistant that speaks the Model Context Protocol.

Manage campaigns, contacts, mailboxes, enrollments, events, and webhooks by chatting with Claude Desktop, Cursor, Windsurf, Cline, Continue, or any custom MCP client — no manual API calls, no clicking through the UI.

Table of Contents

1. What you get
2. Prerequisites
3. Quick start (60 seconds)
4. Integration guides
   • Claude Desktop
   • Cursor
   • Windsurf
   • Cline (VS Code)
   • Continue (VS Code / JetBrains)
   • Zed
   • Custom / CLI clients
5. Available tools
6. Example prompts
7. Real-world use cases
8. Configuration reference
9. Troubleshooting
10. How it works
11. Security notes
12. Contributing

What you get

After installing this server, your AI assistant gains 40 typed tools for ColdBirds Sequence:

| Surface | Examples | |---|---| | Campaigns | list, get, pause, resume, duplicate, update settings, intelligence, variables | | Steps | list / create / update / delete steps in a sequence | | Contacts | list, get, create, update, delete + lists & list-membership | | Enrollments | enroll, list, pause/resume per-contact | | Mailboxes | list, get, create, update, delete sender mailboxes | | Events | list opens / clicks / replies / bounces / unsubscribes | | Webhooks | list, get, test | | Account | who-am-I |

Each tool is backed by the official ColdBirds public REST API and uses the same authentication and rate limits as the dashboard.

Prerequisites

• Node.js 18+ (run node -v to check)
• A ColdBirds account — sign up free at coldbirds.com
• An API key — generate one in Settings → API Keys. Format: sk_live_...

Keys are workspace-scoped. The MCP server can only see / modify resources owned by the workspace that issued the key.

Quick start (60 seconds)

Install globally and verify the server starts:

npm install -g @coldbirds/mcp-server
COLDBIRDS_API_KEY="sk_live_..." coldbirds-mcp

Or run on-demand without installing (recommended for MCP clients — they spawn a fresh process per session):

npx -y @coldbirds/mcp-server

You should see the server idle on stdio. Press Ctrl+C to stop. Now wire it into the AI client of your choice — see Integration guides.

Integration guides

Every client below uses the same launch command: npx -y @coldbirds/mcp-server, with COLDBIRDS_API_KEY injected via environment.

🤖 Claude Desktop

Config file path:

| OS | Path | |---|---| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json | | Linux | ~/.config/Claude/claude_desktop_config.json |

Add a mcpServers entry:

{
  "mcpServers": {
    "coldbirds": {
      "command": "npx",
      "args": ["-y", "@coldbirds/mcp-server"],
      "env": {
        "COLDBIRDS_API_KEY": "sk_live_..."
      }
    }
  }
}

Restart Claude Desktop. Click the 🔌 plug icon in the chat input — you should see coldbirds listed with 40 tools available.

⚡ Cursor

Open Settings → Cursor Settings → MCP (or edit ~/.cursor/mcp.json):

{
  "mcpServers": {
    "coldbirds": {
      "command": "npx",
      "args": ["-y", "@coldbirds/mcp-server"],
      "env": {
        "COLDBIRDS_API_KEY": "sk_live_..."
      }
    }
  }
}

Reload Cursor. In Composer / Chat, type @coldbirds to invoke tools manually, or just ask in plain English ("pause the Q3 outreach campaign") — Cursor will pick the right tool automatically.

🌊 Windsurf

Edit ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "coldbirds": {
      "command": "npx",
      "args": ["-y", "@coldbirds/mcp-server"],
      "env": {
        "COLDBIRDS_API_KEY": "sk_live_..."
      }
    }
  }
}

Restart Windsurf. Tools appear in Cascade's tool picker.

🧩 Cline (VS Code)

Install the Cline extension, then open the Cline panel → MCP Servers → Edit Config:

{
  "mcpServers": {
    "coldbirds": {
      "command": "npx",
      "args": ["-y", "@coldbirds/mcp-server"],
      "env": {
        "COLDBIRDS_API_KEY": "sk_live_..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Leave autoApprove: [] so destructive tools (delete_contact, pause_campaign, etc.) require an explicit confirmation click.

🔧 Continue (VS Code / JetBrains)

Edit ~/.continue/config.json and add to the mcpServers array:

{
  "mcpServers": [
    {
      "name": "coldbirds",
      "command": "npx",
      "args": ["-y", "@coldbirds/mcp-server"],
      "env": {
        "COLDBIRDS_API_KEY": "sk_live_..."
      }
    }
  ]
}

Reload Continue (Cmd+Shift+P → Continue: Reload).

📝 Zed

Open ~/.config/zed/settings.json and add:

{
  "context_servers": {
    "coldbirds": {
      "command": {
        "path": "npx",
        "args": ["-y", "@coldbirds/mcp-server"],
        "env": {
          "COLDBIRDS_API_KEY": "sk_live_..."
        }
      }
    }
  }
}

Restart Zed. Use /coldbirds in the assistant panel.

🛠 Custom / CLI clients

Any client that supports the MCP stdio transport will work. Spawn the server like this:

import { spawn } from "node:child_process";

const server = spawn("npx", ["-y", "@coldbirds/mcp-server"], {
  env: { ...process.env, COLDBIRDS_API_KEY: "sk_live_..." },
  stdio: ["pipe", "pipe", "inherit"],
});

// Speak JSON-RPC 2.0 over server.stdin / server.stdout

Or use the official SDK directly:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

const transport = new StdioClientTransport({
  command: "npx",
  args: ["-y", "@coldbirds/mcp-server"],
  env: { COLDBIRDS_API_KEY: process.env.COLDBIRDS_API_KEY! },
});

const client = new Client({ name: "my-app", version: "1.0.0" });
await client.connect(transport);

const tools = await client.listTools();
console.log(tools.tools.map((t) => t.name)); // 40 tool names

const result = await client.callTool({
  name: "list_campaigns",
  arguments: { limit: 10, status: "ACTIVE" },
});
console.log(result.content);

For interactive exploration, install the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y @coldbirds/mcp-server

This opens a browser UI where you can call every tool and inspect inputs/outputs.

Available tools

40 tools, grouped by surface. Every tool's inputSchema is strict — unknown keys are rejected so your assistant gets accurate validation errors.

| Tool | Method | Path | |---|---|---| | get_account | GET | /api/v1/me |

| Tool | Method | Path | |---|---|---| | list_campaigns | GET | /api/v1/campaigns | | get_campaign | GET | /api/v1/campaigns/{id} | | update_campaign | PATCH | /api/v1/campaigns/{id} | | pause_campaign | POST | /api/v1/campaigns/{id}/pause | | resume_campaign | POST | /api/v1/campaigns/{id}/resume | | duplicate_campaign | POST | /api/v1/campaigns/{id}/duplicate | | get_campaign_stats | GET | /api/v1/campaigns/{id}/stats | | get_campaign_settings | GET | /api/v1/campaigns/{id}/settings | | update_campaign_settings | PATCH | /api/v1/campaigns/{id}/settings | | get_campaign_intelligence | GET | /api/v1/campaigns/{id}/intelligence | | update_campaign_intelligence | PATCH | /api/v1/campaigns/{id}/intelligence |

| Tool | Method | Path | |---|---|---| | list_campaign_steps | GET | /api/v1/campaigns/{campaignId}/steps | | create_campaign_step | POST | /api/v1/campaigns/{campaignId}/steps | | update_campaign_step | PATCH | /api/v1/campaigns/{campaignId}/steps/{stepId} | | delete_campaign_step | DELETE | /api/v1/campaigns/{campaignId}/steps/{stepId} |

| Tool | Method | Path | |---|---|---| | list_contacts | GET | /api/v1/contacts | | get_contact | GET | /api/v1/contacts/{id} | | create_contact | POST | /api/v1/contacts | | update_contact | PATCH | /api/v1/contacts/{id} | | delete_contact | DELETE | /api/v1/contacts/{id} | | list_contact_lists | GET | /api/v1/lists | | create_contact_list | POST | /api/v1/lists | | list_contacts_in_list | GET | /api/v1/lists/{listId}/contacts | | remove_contact_from_list | DELETE | /api/v1/lists/{listId}/contacts/{contactId} |

| Tool | Method | Path | |---|---|---| | enroll_contacts | POST | /api/v1/campaigns/{campaignId}/enrollments | | list_enrollments | GET | /api/v1/campaigns/{campaignId}/enrollments | | get_enrollment | GET | /api/v1/enrollments/{id} | | pause_enrollment | POST | /api/v1/enrollments/{id}/pause | | resume_enrollment | POST | /api/v1/enrollments/{id}/resume |

| Tool | Method | Path | |---|---|---| | list_mailboxes | GET | /api/v1/mailboxes | | get_mailbox | GET | /api/v1/mailboxes/{id} | | create_mailbox | POST | /api/v1/mailboxes | | update_mailbox | PATCH | /api/v1/mailboxes/{id} | | delete_mailbox | DELETE | /api/v1/mailboxes/{id} |

| Tool | Method | Path | |---|---|---| | list_events | GET | /api/v1/events | | list_webhooks | GET | /api/v1/webhooks | | get_webhook | GET | /api/v1/webhooks/{id} | | test_webhook | POST | /api/v1/webhooks/{id}/test |

| Tool | Method | Path | |---|---|---| | get_campaign_variables | GET | /api/v1/campaigns/{campaignId}/variables |

The live, machine-readable tool catalogue lives at https://sequencer.coldbirds.com/mcp.json.

Example prompts

Just talk to your assistant in plain English. It will pick the right tool, ask for confirmation on destructive actions, and chain calls when needed.

🔎 Insights

"Show me my top 5 campaigns by reply rate this month."

"Which mailboxes had deliverability issues in the last 7 days?"

"Summarise opens, clicks, and replies for the Q3 founder outreach campaign."

"Pull the 10 most recent bounces and group them by mailbox."

✏️ Campaign management

"Pause all campaigns sending from [email protected] — that mailbox needs a break."

"Duplicate the 'SaaS CEOs - Cycle 4' campaign, rename to 'Cycle 5', and update step 2's subject to 'One quick question, {{first_name}}'."

"In the 'Series A Founders' sequence, change the wait between step 3 and step 4 from 3 days to 5 business days."

"Show me the variables available in campaign cmp_abc123 and tell me which ones are unused in any step."

👥 Contact ops

"Find every contact at acme.com and add them to the list 'ACME — Q3 push'."

"Create a new contact: Jane Doe, [email protected], CTO at Example Corp, then enroll her in campaign cmp_xyz789 starting today."

"Delete contact con_def456 — they unsubscribed via reply."

📮 Mailbox ops

"List all mailboxes that aren't currently warming up."

"Update the daily-send-limit on every mailbox tagged tier-1-senders to 80."

"Connect a new SMTP mailbox: smtp.fastmail.com:465, user [email protected], then send a test."

🛠 Webhook / integrations

"List my webhooks. For each, run test_webhook and report which ones don't return 200."

🧠 Agentic workflows

"Every Monday at 9am, summarise last week's campaign performance, pause anything with <2% reply rate, and post a one-paragraph standup to my notes."

"I'm replying to a prospect. Pull their enrollment history, last event, and the original cold email I sent so I have full context."

Real-world use cases

1. Morning ops standup (read-only)

"Give me a 5-bullet brief: total sends yesterday, reply rate, any mailbox health alerts, top 3 replied campaigns, and any contacts that bounced more than once this week."

The assistant chains list_campaigns → get_campaign_stats → list_mailboxes → list_events?type=BOUNCED and assembles a report in seconds.

2. Reply triage from your inbox

Pair the MCP server with a Gmail / Outlook tool in the same client. When a prospect replies, ask:

"@coldbirds find this contact, show their enrollment status, and pause any future steps for them in campaign X."

3. Bulk campaign edits from spec

Paste a markdown spec ("rewrite step 2 to be more concise, change wait to 4 days, add a P.S. line") and let the assistant call update_campaign_step to apply the edits — no copy-paste through the UI.

4. List hygiene

"Find contacts in my workspace that have bounced in the last 30 days and remove them from all active lists."

The assistant uses list_events?type=BOUNCED → list_contact_lists → remove_contact_from_list in a loop.

5. Cross-tool agents (Notion / Linear / GitHub)

Combine with other MCP servers — e.g. when a Linear issue tagged outreach is created, your agent can run duplicate_campaign + enroll_contacts based on the issue body.

Configuration reference

| Variable | Required | Default | Description | |---|---|---|---| | COLDBIRDS_API_KEY | ✅ | — | Your sk_live_... key from Settings → API Keys. | | COLDBIRDS_API_URL | ❌ | https://sequencer.coldbirds.com | Override only for self-hosted or staging deployments. |

The server fetches its tool catalogue from ${COLDBIRDS_API_URL}/mcp.json at startup (5 s timeout). If the live manifest is unreachable or fails validation, it falls back to a snapshot bundled inside this package — so the server always starts even when offline.

Troubleshooting

1. Quit Claude Desktop completely (Cmd+Q on macOS, not just close the window).
2. Verify the config JSON parses: cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | jq .
3. Try the command in a terminal:

   COLDBIRDS_API_KEY="sk_live_..." npx -y @coldbirds/mcp-server

   It should print nothing and wait for input (that's normal — MCP servers talk over stdio).
4. Check the log: ~/Library/Logs/Claude/mcp-server-coldbirds.log.

You're behind a registry proxy. Pre-install it once: npm install -g @coldbirds/mcp-server, then use command: "coldbirds-mcp" (without npx) in your client config.

The API key is wrong, revoked, or missing the sk_live_ prefix. Regenerate at Settings → API Keys and update your client config.

The live mcp.json couldn't be reached or didn't match the expected schema. The server still works — it's running off the snapshot bundled with the package version you installed. Run npm install -g @coldbirds/mcp-server@latest to get the newest snapshot.

Run via the MCP Inspector:

npx @modelcontextprotocol/inspector npx -y @coldbirds/mcp-server

The Inspector shows every JSON-RPC request and response in real time. For deeper debugging, set NODE_OPTIONS=--inspect and attach Chrome DevTools.

How it works

┌──────────────────┐      stdio (JSON-RPC 2.0)      ┌────────────────────┐
│ AI assistant     │ ◀────────────────────────────▶ │ @coldbirds/        │
│ (Claude, Cursor, │                                │  mcp-server        │
│  Cline, …)       │                                │                    │
└──────────────────┘                                └─────────┬──────────┘
                                                              │  HTTPS + Bearer
                                                              ▼
                                                    ┌────────────────────┐
                                                    │ sequencer.         │
                                                    │  coldbirds.com     │
                                                    │  /api/v1/*         │
                                                    └────────────────────┘

• Single source of truth: the tool catalogue is published at https://sequencer.coldbirds.com/mcp.json and the server registers tools in a loop. New ColdBirds API endpoints become MCP tools automatically — no code change in this package.
• Strict validation: every tool's inputSchema is converted to a strict Zod schema before registration. Unknown keys are rejected at the SDK boundary so your assistant gets a clear error instead of a silent strip.
• Offline-safe: a snapshot of the manifest is bundled at build time. If the live fetch fails, the server falls back to the snapshot and logs a one-line stderr warning.

Architecture & contribution rules are documented in the root AGENTS.md §21.

Security notes

• 🔐 Treat your API key like a password. Never paste it in chat, never commit it to git, never share it in screenshots.
• 🛡 Workspace-scoped: keys can only see and modify the workspace that issued them. They cannot access other workspaces or platform-level resources.
• ⚠️ Destructive tools (delete_contact, delete_mailbox, delete_campaign_step, pause_campaign, etc.) carry the MCP destructiveHint: true annotation. Configure your client to require explicit approval for them — do NOT add them to an auto-approve allow-list unless you fully trust the prompts.
• 🚦 Rate limits: the same per-key limits as the dashboard apply (currently 60 req/min). The server doesn't add additional throttling — bursty agentic loops will hit 429 and back off.
• 🔭 Audit log: every API call shows up in your workspace's audit log under the issuing key's name.

Contributing

This package is part of the coldbirds/sequence monorepo. PRs are welcome.

• Adding a tool → just edit public/mcp.json at the repo root; the dispatcher picks it up automatically. Full instructions in AGENTS.md §21.2.
• Bug reports / feature requests → open an issue.
• Local dev:

  git clone https://github.com/elitale/coldbird-sequncer.git
  cd coldbird-sequncer
  npm ci
  cd packages/mcp
  npm test         # 111 tests
  npm run build
  npm start

License

MIT © Elitale Technologies

Built with ❤️ for cold-email marketers who would rather chat than click.