plunk-mcp

A Model Context Protocol server for Plunk, the open-source self-hosted email platform. Gives Claude (and any MCP client) 84 tools across the Plunk API: transactional email, contacts, campaigns, segments, templates, workflows, events, analytics.

Unofficial. Not affiliated with Plunk. Built by Ignyte.

Why this exists

Plunk's official Node SDK does two things: track and send. The API behind those two methods has grown into a full email automation platform that includes workflows, segments, templates, analytics, but the SDK never caught up. So Claude couldn't reach any of it.

This MCP closes that gap. Every endpoint Claude can usefully call, it can call.

Requirements

The active Plunk codebase: useplunk/plunk, distributed as ghcr.io/useplunk/plunk. Self-hosted or on useplunk.com.

Note that this MCP does not support the legacy driaug/plunk Docker image. If you're on that image, see Migrating from legacy.

Node.js ≥ 18 if you're running from source.

Install

Add to ~/.claude.json or your Claude Desktop config:

{
  "mcpServers": {
    "plunk": {
      "command": "npx",
      "args": ["-y", "@ignytehq/plunk-mcp"],
      "env": {
        "PLUNK_API_KEY": "sk_your_secret_key_here",
        "PLUNK_PUBLIC_KEY": "pk_your_public_key_here",
        "PLUNK_API_URL": "https://your-plunk-host"
      }
    }
  }
}

Restart Claude.

PLUNK_PUBLIC_KEY is optional. Plunk's /v1/track endpoint is gated by the public key (pk_*), not the secret key — if you omit PLUNK_PUBLIC_KEY, plunk_track_event will 401 against v0.10+ instances.

Multiple Plunk projects

Plunk API keys are project-scoped. To work with multiple projects in the same session, register one MCP server per project:

{
  "mcpServers": {
    "plunk-acme": {
      "command": "npx",
      "args": ["-y", "@ignytehq/plunk-mcp"],
      "env": {
        "PLUNK_API_KEY": "sk_acme_...",
        "PLUNK_API_URL": "https://plunk.acme.com"
      }
    },
    "plunk-personal": {
      "command": "npx",
      "args": ["-y", "@ignytehq/plunk-mcp"],
      "env": {
        "PLUNK_API_KEY": "sk_personal_...",
        "PLUNK_API_URL": "https://plunk.example.com"
      }
    }
  }
}

Claude sees each as its own tool namespace.

Configuration

| Env var | Required | Default | What it does | |---|---|---|---| | PLUNK_API_KEY | yes | — | Secret API key (sk_*) from your project settings. Used for all admin endpoints and for /v1/send / /v1/verify. | | PLUNK_PUBLIC_KEY | no | — | Public API key (pk_*). Required for plunk_track_event — Plunk's /v1/track endpoint is gated by the public key, not the secret key. Without this set, track_event will 401. | | PLUNK_API_URL | no | https://api.useplunk.com | Base URL of your Plunk API. For self-hosted, point at the API host (e.g. https://api.plunk.example.com, or https://plunk.example.com/api if your reverse proxy maps it that way). | | PLUNK_SKIP_CAPABILITY_DETECTION | no | false | Skip the startup probe and expose every tool regardless of what your instance supports. Useful for debugging. |

What's in the box

84 tools across 11 categories. At startup, the MCP probes one endpoint per category and only registers tools whose category responds — so on older useplunk/plunk releases, missing features are hidden rather than failing at call time.

| Category | Tools | Highlights | |---|---|---| | Transactional | 3 | send_transactional, track_event, verify_email | | Contacts | 18 | CRUD, bulk import/subscribe/unsubscribe/delete, custom field management | | Campaigns | 10 | Full lifecycle: create, update, send, cancel, test, stats | | Segments | 10 | Dynamic + static segments, member management, recompute | | Templates | 7 | Reusable email templates referenced from sends/campaigns/workflows | | Workflows | 16 | Steps, transitions, executions — the whole automation builder | | Events | 6 | Read API: history, stats, names, usage, delete | | Domains | 4 | Add, verify, delete sending domains | | Activity | 5 | Activity feed, stats, upcoming sends | | Analytics | 4 | Timeseries, top campaigns, top events | | Uploads | 1 | Image uploads for templates and campaigns |

Tool names follow plunk_<verb>_<resource>. Examples:

• plunk_send_transactional — send a one-off email
• plunk_track_event — fire an event (which then drives workflows and segment filters)
• plunk_create_workflow + plunk_add_workflow_step + plunk_start_workflow_execution
• plunk_create_segment (full filter-condition schema)
• plunk_get_analytics_timeseries, plunk_get_top_campaigns

Every tool has a typed input schema. Claude knows what to pass.

Capability detection, briefly

On startup the MCP makes one probe request per tool family to see what your instance answers. If /templates 404s, the seven template tools are hidden for the rest of the session. If /workflows answers, the sixteen workflow tools are registered.

The point is to keep Claude from confidently invoking endpoints that don't exist on your specific Plunk version. The probe takes one round trip per family at startup, then nothing.

Migrating from legacy driaug/plunk

The legacy image exposes a smaller, different API. This MCP won't fully work against it. The migration path:

1. Stand up ghcr.io/useplunk/plunk:latest on a separate host or subdomain. Don't disrupt your existing sender. The official guide is at docs.useplunk.com/self-hosting/introduction.
2. Re-create your project on the new instance. Grab a fresh sk_* API key. The schemas differ; there's no in-place upgrade.
3. Export contacts from legacy (CSV from the dashboard). Import on the new instance via plunk_import_contacts.
4. Re-create campaigns and templates. Workflows and segments are entirely new on the modern codebase.
5. Repoint your apps to the new host. Decommission legacy.

This is a real migration project, an easy evening or two of work.

Building from source

git clone https://github.com/ignytehq/plunk-mcp.git
cd plunk-mcp
npm install
npm run build
PLUNK_API_KEY=sk_... PLUNK_API_URL=https://your-plunk node dist/index.js

Contributing

Issues and PRs welcome. If an endpoint responds unexpectedly, please include:

• Which Plunk version you're running (docker inspect <container> | grep Image plus the tag)
• The endpoint path that misbehaved
• The full error message

License

MIT. See LICENSE.

Acknowledgements

Plunk and Driaug Aerts, for being open source. Anthropic, for the Model Context Protocol.