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.

Related MCP server: Email MCP

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

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.

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.