@postwave/mcp-server

The official Postwave Model Context Protocol (MCP) server. Wraps the Postwave API so any MCP-aware agent — Claude Code, Cursor, Claude Desktop, Continue, Zed — can drive newsletter migrations, deliverability diagnostics, voice-trained AI sequences, subscriber management, forms, automations, and campaigns.

MIT licensed. Source mirror: github.com/postwave/mcp-server. Issues, PRs, and forks welcome.

What it does

• Migrate from Mailchimp, ConvertKit, Substack, Beehiiv, MailerLite, or CSV — agent-driven, with dry-run + 7-day rollback.
• Diagnose deliverability — campaign-level reports across 30 seedlist inboxes, SPF/DKIM/DMARC/BIMI checks, AI Diagnostician fixes.
• Predict placement before you send.
• Generate voice-fingerprinted email sequences using your existing writing.
• Manage subscribers, segments, forms, and behavioral automations.
• Compose + send campaigns including A/B tests.

53 tools, 7 resources, 8 worked-example prompts. See tool catalogue below.

Install

Claude Code (recommended)

claude mcp add postwave -e POSTWAVE_API_KEY=pw_xxx -- npx -y @postwave/mcp-server

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "postwave": {
      "command": "npx",
      "args": ["-y", "@postwave/mcp-server"],
      "env": { "POSTWAVE_API_KEY": "pw_xxx" }
    }
  }
}

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "postwave": {
      "command": "npx",
      "args": ["-y", "@postwave/mcp-server"],
      "env": { "POSTWAVE_API_KEY": "pw_xxx" }
    }
  }
}

Restart Claude Desktop. The Postwave tools should appear under the hammer icon.

Continue

Add to your Continue config (~/.continue/config.json):

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["-y", "@postwave/mcp-server"]
        }
      }
    ]
  }
}

Set POSTWAVE_API_KEY in your shell environment.

Hosted (HTTP/SSE)

Skip the install entirely:

https://mcp.postwave.app/mcp

OAuth handles auth. Self-hosting the HTTP transport: set POSTWAVE_MCP_TRANSPORT=http and PORT=3030, then point your client at http://localhost:3030/mcp with Authorization: Bearer pw_xxx.

Environment variables

| Var | Required | Default | Notes | |---|---|---|---| | POSTWAVE_API_KEY | yes | — | Your Postwave API key (pw_…). | | POSTWAVE_BASE_URL | no | https://api.postwave.app | Override for self-hosted or staging. | | POSTWAVE_TENANT_ID | no | — | Tenant slug. Omit when your API key is tenant-scoped. | | POSTWAVE_MCP_TRANSPORT | no | stdio | stdio or http. | | PORT | no | 3030 | HTTP transport port. |

Tool catalogue

53 tools across 11 categories. Each tool input is Zod-validated; URL parameters get an SSRF guard; results are capped at 5 MB and timed out at 30 s (60 s for migration jobs).

Migration (6)

• migrate_start — begin OAuth handshake with a source platform; returns authorize_url + state.
• migrate_discover — pre-flight inventory of subscribers, lists, automations, archives in the source account.
• migrate_dry_run — simulate the import; produces a verification report without writing data.
• migrate_commit — execute the full migration into Postwave.
• migrate_status — poll a migration job by ID.
• migrate_rollback — revert a completed migration within the 7-day window.

Deliverability (6)

• diagnose_campaign — run the AI Diagnostician on a sent campaign; returns ranked fixes.
• predict_placement — predict inbox placement (Primary / Promotions / Spam) before send from raw HTML + subject.
• check_reputation — domain + IP sender reputation snapshot.
• check_auth — SPF, DKIM, DMARC, BIMI status.
• render_cross_client — render an HTML email across Gmail, Outlook, Apple Mail, Yahoo, etc.
• inbox_report — full Inbox Reality report for a campaign across the seedlist.

Voice + Sequences (5)

• voice_profile_get — current tenant voice fingerprint.
• voice_source_add — register a new ingestion source (RSS, Twitter, transcript, paste).
• voice_profile_build — rebuild the profile from currently-ingested sources.
• sequence_generate — generate a sequence from one of the 50 templates in the user's voice.
• sequence_regenerate_email — regenerate a single email in a sequence with an optional hint.

Subscribers + Segments (10)

• subscribers_list, subscribers_search, subscriber_create, subscriber_suppress.
• custom_field_create — declare a tenant custom field.
• segment_create, segment_list, segment_delete — manage saved segments.
• segment_compile_from_text — natural-language → SegmentNode AST.
• segment_eval — evaluate a canonical AST and return matching count + sample.

Forms (5)

• form_create, form_update, form_delete, form_submissions_list.
• optin_confirm — confirm a pending double-opt-in via token.

Automations (6)

• automation_create, automation_list, automation_update.
• automation_create_behavioral_trigger — wire open/click/no-open triggers.
• automation_trigger — fire for one subscriber.
• automation_pause — pause OR resume an automation.

Campaigns + A/B (6)

• campaign_create, campaign_send, campaign_create_ab, campaign_ab_results.
• paid_sub_create — native Stripe-mirrored paid subscription.
• send_test_email — one-off transactional preview.

Topics (5)

• topic_create, topic_list, topic_delete, topic_subscribe, topic_unsubscribe.

Admin — Webhooks + API Keys (8)

• webhook_create, webhook_list, webhook_delete, webhook_test_fire, webhook_deliveries_list.
• api_key_create, api_key_list, api_key_revoke — privileged; require explicit human approval.

Agent primitives (6)

• audit_query, approvals_list, approvals_decide, sandbox_status, cost_aggregate, safety_check.

Events (1)

• events_subscribe — declarative subscription; events flow to postwave://events/stream.

Resources

• postwave://voice-profile — current voice fingerprint JSON (~3 KB).
• postwave://recent-migrations — last 10 migration jobs.
• postwave://recent-campaigns — last 10 campaigns with placement summaries.
• postwave://templates — full 50-template library.
• postwave://sequences — active sequences for the tenant.
• postwave://inbox-reality/{campaign_id} — full report for a specific campaign (templated).
• postwave://events/stream{?type,campaign} — latest 50 deliverability events; pull-only, poll every 10–30s (templated, FF).

Prompts

Eight worked-example operations agents can invoke directly:

• migrate-from-mailchimp
• diagnose-last-campaign
• write-welcome-sequence
• improve-deliverability
• audit-list-hygiene
• weekly-newsletter-from-rss
• re-engage-cold-subscribers
• setup-double-optin-form

Troubleshooting

• "POSTWAVE_API_KEY is not set" — the server won't start without it. Get a key from the Postwave dashboard → Settings → API keys.
• Tools don't appear in Claude Desktop — restart the app fully (Quit, then re-open). Then check the Claude logs at ~/Library/Logs/Claude/mcp*.log.
• spawn npx ENOENT — Claude Desktop on macOS sometimes can't find npx. Use the absolute path: "command": "/usr/local/bin/npx" (or which npx to find yours).
• HTTP transport returns 401 — Authorization header must be Bearer pw_…. The hosted server at mcp.postwave.app uses OAuth instead.
• Tool timeout — defaults are 30 s for everything except migrate_* which get 60 s. Long migrations should be polled via migrate_status rather than waiting on migrate_commit.

Contributing

See CONTRIBUTING.md. Security issues: SECURITY.md.

License

MIT. See LICENSE.