cheapinboxes-mcp

MCP server for the CheapInboxes API plus Porkbun domain buying — run the whole cold-email infrastructure pipeline from any MCP client (Claude Code, Cursor, Claude Desktop, …) instead of clicking through dashboards:

buy domains on Porkbun → import them into CheapInboxes → provision Google/Microsoft mailboxes → grab credentials / sync to Instantly, Smartlead, EmailBison, PlusVibe.

32 tools: 8 for Porkbun, 21 for CheapInboxes, two raw escape hatches that reach every endpoint of both APIs, and a runbook tool that teaches the model the end-to-end flow.

Setup

Requires Node 18+ (uses global fetch).

git clone https://github.com/cosankov/cheapinboxes-mcp.git
cd cheapinboxes-mcp
npm install

Keys

Variable	Where to get it	Needed for
CHEAPINBOXES_API_KEY	CheapInboxes dashboard → Integrations → API	all ci_* tools
PORKBUN_API_KEY + PORKBUN_SECRET_KEY	porkbun.com → Account → API Access (enable API access per domain too)	all porkbun_* tools

The two sides are independent — with only a CheapInboxes key the porkbun_* tools error cleanly and everything else works, and vice versa.

Keys are read from process.env first, then from the first .env file found: $CHEAPINBOXES_MCP_ENV → .env next to server.mjs. Easiest: copy your keys into a .env in the repo root (gitignored):

CHEAPINBOXES_API_KEY=ci_live_...
PORKBUN_API_KEY=pk1_...
PORKBUN_SECRET_KEY=sk1_...

Register with your MCP client

Claude Code / Cursor (.mcp.json):

{
  "mcpServers": {
    "cheapinboxes": {
      "command": "node",
      "args": ["/absolute/path/to/cheapinboxes-mcp/server.mjs"]
    }
  }
}

(Or pass the keys via the "env" block instead of a .env file.)

Verify

npm run smoke

Boots the server over stdio, lists all tools, live-pings Porkbun, and checks the CheapInboxes key — each side reports [OK] or a clean error telling you which key is missing.

The flow

Ask your MCP client to run the runbook tool, or follow it yourself:

1. porkbun_check_domain per candidate — availability + live price. Rate limit: 1 check / 10 s.
2. porkbun_register_domain — dry_run defaults to true (preview, no charge); pass dry_run: false to buy. cost_cents must exactly match the checked price (Porkbun's own guard). Live runs auto-send an Idempotency-Key, so retries can't double-charge.
3. ci_stage_imports with the purchased domains (source_provider: "porkbun").
4. ci_quote — cart of {domain, tld, staged_import_id, mailboxes: {provider, count}}; imported domains are $0.
5. ci_checkout — same cart with mailbox personas {first_name, last_name, email_prefix}; optional integration_id auto-connects mailboxes to a sending platform. Charges the card on file.
6. Poll ci_list_domains with the returned order_id until nameservers appear (or ci_domain_nameservers per domain).
7. porkbun_set_nameservers — point each domain at the CheapInboxes nameservers.
8. Poll ci_get_domain until status: "active" (include_runs: true adds provisioning-step history for debugging).
9. ci_mailbox_credentials for logins (password, app password, IMAP/SMTP) or ci_sync_integration to push mailboxes to your sequencer.

Tool map

Area	Tools
Guide	runbook
Porkbun	porkbun_ping, porkbun_pricing, porkbun_check_domain, porkbun_register_domain ⚠💰, porkbun_list_domains, porkbun_get_nameservers, porkbun_set_nameservers, porkbun_dns
CheapInboxes discovery	ci_org, ci_tld_pricing, ci_mailbox_pricing, ci_search_domains
Import → order	ci_stage_imports, ci_list_staged_imports, ci_remove_staged_import, ci_quote, ci_checkout ⚠💰, ci_get_order
Domains	ci_list_domains, ci_get_domain, ci_domain_nameservers
Mailboxes	ci_list_mailboxes, ci_get_mailbox, ci_mailbox_credentials 🔐, ci_create_mailboxes ⚠💰, ci_update_mailbox
Platform sync	ci_list_integrations, ci_sync_integration
Billing	ci_billing_summary
Escape hatches	ci_api (any CheapInboxes endpoint), porkbun_api (any Porkbun endpoint)

⚠💰 = spends real money. 🔐 = returns secrets.

The escape hatches cover everything not curated: CheapInboxes DNS records, DMARC, forwarding, webhooks, cancellations, invoices, TOTP codes, org members; Porkbun SSL bundles, glue records, email forwarding, contacts, marketplace.

Safety rails

• porkbun_register_domain previews by default; a purchase requires an explicit dry_run: false, an exact cost_cents match, and gets an idempotency key.
• ci_checkout has no server-side dry run — always run ci_quote first (identical cart shape, so it's a copy-paste).
• Rate limits: CheapInboxes 120 req/min; Porkbun 1 availability check / 10 s, 1 registration attempt / 10 s, 50 registrations / day.
• Porkbun sandbox: use pk1_sb_ / sk1_sb_ keys (and PORKBUN_BASE_URL if needed) to rehearse purchases with fake credit.

License

MIT