Skip to content

MCP Server Integration

Subscribe Flow provides an MCP server (Model Context Protocol) that enables LLM agents like Claude to interact directly with the Subscribe Flow API.

Plan Requirement

MCP access requires a Starter or Professional plan. Free-tier organizations will receive a 403 Forbidden error with plan_required on the first tool call. Upgrade via GET /api/v1/billing/checkout.

What is MCP?

The Model Context Protocol (MCP) is a protocol developed by Anthropic that securely connects LLMs with external tools. The Subscribe Flow MCP server exposes 66 tools for managing subscribers, tags, templates, emails, campaigns, triggers, webhooks, billing, the preference center, and platform administration.

All MCP tools are organization-scoped via the API key. The MCP server automatically filters all operations to the organization associated with the configured API key.

Installation

Bash
1
pip install "subscribeflow[mcp]"

Configuration

Claude Desktop

Path to configuration file: - macOS: ~/Library/Application Support/Claude/claude_desktop_config.json - Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 1: With uv (Recommended)

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Option 2: With full path

After installing with pip install "subscribeflow[mcp]":

Bash
1
2
3
# Find the path
which subscribeflow-mcp
# Example: /Users/username/.local/bin/subscribeflow-mcp
JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
{
  "mcpServers": {
    "subscribeflow": {
      "command": "/Users/username/.local/bin/subscribeflow-mcp",
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Option 3: With Python module

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
{
  "mcpServers": {
    "subscribeflow": {
      "command": "/opt/homebrew/bin/python3",
      "args": ["-m", "subscribeflow.mcp.server"],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

The production URL https://api.subscribeflow.net is set as the default.

Claude Code

Add the configuration to ~/.claude.json or ~/.claude/settings.json.

With uv (Recommended):

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_live_xxx"
      }
    }
  }
}

Local Development

For a local Subscribe Flow instance, add SUBSCRIBEFLOW_BASE_URL:

JSON
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
{
  "mcpServers": {
    "subscribeflow": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/subscribe-flow/sdk/python",
        "run", "subscribeflow-mcp"
      ],
      "env": {
        "SUBSCRIBEFLOW_API_KEY": "sf_dev_xxx",
        "SUBSCRIBEFLOW_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Use Cases

1. Newsletter Management

Text Only
1
2
3
4
5
6
You: "Add max@example.com to the Weekly Newsletter"

Claude: I'll create the subscriber and assign the tag.
        [create_subscriber, get_or_create_tag]

        Done! max@example.com has been added to "Weekly Newsletter".

2. Subscriber Analysis

Text Only
1
2
3
4
5
6
7
8
9
You: "How many active subscribers do we have in the 'product-updates' tag?"

Claude: [get_tag_by_name, list_subscribers]

        The "product-updates" tag has 1,247 active subscribers.
        The 5 most recent sign-ups:
        - anna@example.com (2 hours ago)
        - tom@example.com (5 hours ago)
        ...

3. Bulk Tag Creation

Text Only
1
2
3
4
5
6
7
8
You: "Create tags for our product categories: Electronics, Fashion, Home"

Claude: [create_tag x3]

        All three tags have been created:
        - Electronics (ID: abc123)
        - Fashion (ID: def456)
        - Home (ID: ghi789)
Text Only
1
2
3
4
5
6
7
You: "Generate a preference center link for support@customer.com"

Claude: [get_subscriber_by_email, generate_preference_token]

        Here is the link:
        https://subscribeflow.net/preferences?token=eyJ...
        (Valid for 7 days)

5. Billing & Usage Check

Text Only
1
2
3
4
5
6
7
8
You: "How many subscribers can we still add this month?"

Claude: [get_subscription, get_usage]

        Your plan: Starter
        - Subscribers: 3,421 / 5,000 (1,579 remaining)
        - Emails: 12,340 / 10,000 this month
        - Webhooks: 2 / 3 configured
Text Only
1
2
3
4
5
6
7
8
You: "Find all subscribers with @company.com email addresses"

Claude: [list_subscribers]

        Found: 23 subscribers with @company.com:
        - admin@company.com (active, Tags: newsletter, updates)
        - sales@company.com (active, Tags: newsletter)
        ...

7. Tag Statistics

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
You: "Show me an overview of all tags with subscriber counts"

Claude: [list_tags]

        Tag overview:
        | Tag              | Subscribers | Public |
        |------------------|-------------|--------|
        | Newsletter       | 5,234       | Yes    |
        | Product Updates  | 1,247       | Yes    |
        | Internal         | 42          | No     |

8. Webhook Monitoring

Text Only
1
2
3
4
5
6
7
8
You: "Test all configured webhooks"

Claude: [list_webhooks, test_webhook x3]

        Webhook test results:
        - Main Webhook (https://app.com/hook): OK (127ms)
        - Backup (https://backup.com/hook): OK (234ms)
        - Analytics (https://analytics.com/hook): ERROR (Timeout)

9. Subscriber Migration

Text Only
1
2
3
4
5
6
7
8
You: "Move all subscribers from the 'old-newsletter' tag to 'new-newsletter'"

Claude: [get_tag_by_name x2, list_subscribers, update_subscriber x...]

        Migration completed:
        - 847 subscribers moved
        - 3 already in the new tag (skipped)
        - 0 errors

10. Automating Welcome Emails

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
You: "Set up an automatic welcome email that is sent when new subscribers
     sign up"

Claude: [list_templates, create_trigger]

        Trigger created:
        - Event: subscriber.created
        - Template: "Welcome Email" (welcome-email)
        - Status: active

        From now on, every new subscriber will automatically receive the
        welcome email.

11. Sending a Newsletter Campaign

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
You: "Create a campaign for the February newsletter and send it to all
     newsletter subscribers"

Claude: [list_tags, list_templates, create_campaign, count_campaign_recipients,
         send_campaign]

        Campaign "February Newsletter 2026" created and started:
        - Template: Monthly Newsletter
        - Recipients: 3,421 (Tag: newsletter)
        - Status: sending

        Sending is running in the background. You can check the progress with
        "Show the status of the February campaign".

12. Previewing a Template

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
You: "Show me a preview of the welcome email with company data for Acme AG"

Claude: [get_template_by_slug, preview_template]

        Here is the preview for "Welcome Email":
        - Subject: "Welcome to Acme AG!"
        - HTML preview generated

        The template variables have been populated:
        - {{company}} -> "Acme AG"
        - {{year}} -> "2026"

13. Analyzing Webhook Deliveries

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
You: "Show me the delivery statistics for our main webhook"

Claude: [list_webhooks, get_webhook_delivery_stats]

        Webhook "Main Production" (https://app.com/hook):
        - Total: 12,847 deliveries
        - Successful: 12,691 (98.8%)
        - Failed: 156 (1.2%)
        - Average response time: 142ms

        Would you like me to show the failed deliveries?

14. GDPR Data Export

Text Only
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
You: "Export all stored data for privacy@customer.com"

Claude: [get_subscriber_by_email, generate_preference_token,
         preference_center_get_info, preference_center_export_data]

        Data export for privacy@customer.com created:
        - Subscriber profile: active since 2025-03-15
        - Subscribed tags: Newsletter, Product Updates
        - Metadata: source=website, plan=premium
        - Audit log: 23 entries
        - Exported on: 2026-02-15, 10:30 AM

15. Checking Campaign Recipients in Advance

Text Only
1
2
3
4
5
6
7
8
9
You: "How many subscribers would receive a campaign targeting 'premium'
     but not 'churned'?"

Claude: [count_campaign_recipients]

        Recipient check:
        - Include: Tag "premium"
        - Exclude: Tag "churned"
        - Result: 847 active subscribers would receive the campaign

Available Tools (66 total)

Subscriber Tools (8)

Tool Description
list_subscribers List subscribers (with filters, org-scoped)
get_subscriber Get a subscriber by ID
get_subscriber_by_email Get a subscriber by email
create_subscriber Create a new subscriber
get_or_create_subscriber Idempotently create/retrieve
update_subscriber Update a subscriber
delete_subscriber Delete a subscriber
generate_preference_token Generate a preference center token

Tag Tools (7)

Tool Description
list_tags List tags (org-scoped)
get_tag Get a tag by ID
get_tag_by_name Get a tag by name
create_tag Create a new tag
get_or_create_tag Idempotently create/retrieve
update_tag Update a tag
delete_tag Delete a tag

Template Tools (7)

Tool Description
list_templates List email templates
get_template Get a template by ID
get_template_by_slug Get a template by slug
create_template Create a new MJML template
update_template Update a template
delete_template Delete a template
preview_template Render a template with variables

Email Tools (1)

Tool Description
send_email Send a transactional email via template

Campaign Tools (7)

Tool Description
list_campaigns List campaigns (with status filter)
get_campaign Get a campaign by ID (with statistics)
create_campaign Create a new campaign in draft status
update_campaign Update a draft campaign
send_campaign Send a campaign to all recipients
cancel_campaign Cancel a running campaign
count_campaign_recipients Count recipients for a tag filter

Trigger Tools (5)

Tool Description
list_triggers List email triggers
get_trigger Get a trigger by ID
create_trigger Create an event-based trigger
update_trigger Update a trigger
delete_trigger Delete a trigger

Billing Tools (2)

Tool Description
get_subscription Get current plan, tier, and limits
get_usage Get usage statistics (subscribers, emails, webhooks)

Webhook Tools (5 basic + 9 extended)

Tool Description
list_webhooks List webhooks (org-scoped)
get_webhook Get a webhook by ID
create_webhook Create a new webhook
delete_webhook Delete a webhook
test_webhook Test a webhook
update_webhook Update webhook configuration
rotate_webhook_secret Rotate the signing secret
list_webhook_deliveries View delivery history
get_webhook_delivery Get a single delivery with payload
get_webhook_delivery_stats Get delivery statistics
retry_webhook_delivery Retry a failed delivery
list_webhook_event_types List available event types
enable_webhook Enable a webhook
disable_webhook Disable a webhook

Preference Center Tools (5)

Tool Description
preference_center_get_info Get subscriber preferences and available tags
preference_center_subscribe_tag Subscribe to a tag via the preference center
preference_center_unsubscribe_tag Unsubscribe from a tag via the preference center
preference_center_export_data Perform a GDPR data export
preference_center_delete_account Request GDPR account deletion

Platform Admin Tools (10)

Zugriff eingeschränkt

Diese Tools funktionieren ausschließlich mit API Keys von Organisationen, bei denen is_platform_admin = true gesetzt ist (aktuell nur Talent Factory GmbH). Anfragen mit regulären API Keys erhalten 403 Forbidden.

Tool Description
admin_list_organizations List all organizations on the platform
admin_get_organization Get organization details by ID
admin_update_organization Update organization settings
admin_delete_organization Delete an organization
admin_list_users List all platform users
admin_get_user Get user details by ID
admin_list_members List members of an organization
admin_add_member Add a user to an organization
admin_remove_member Remove a user from an organization
admin_get_platform_stats Get platform-wide statistics

Security

API Key Scopes

For the MCP server, we recommend an API key with the required scopes:

Text Only
1
2
3
4
5
6
subscribers:read
subscribers:write
tags:read
tags:write
templates:read
templates:write

Optional (only if needed):

Text Only
1
2
3
4
webhooks:manage
campaigns:manage
triggers:manage
billing:read

Destructive Operations

The tools delete_subscriber, delete_tag, delete_webhook, delete_template, delete_trigger, and cancel_campaign are marked as destructive. Claude will ask for confirmation before executing them.

Troubleshooting

MCP Server Does Not Start

  1. Check whether the package is installed:

    Bash
    1
    pip show subscribeflow

  2. Test the server manually:

    Bash
    1
    SUBSCRIBEFLOW_API_KEY=sf_live_xxx subscribeflow-mcp

"Unauthorized" Error

  • Check the API key: It should start with sf_live_ or sf_test_
  • Verify the key permissions in the admin dashboard

"Plan Required" Error (403)

  • MCP access requires at least the Starter plan
  • Check your current plan: GET /api/v1/billing/subscription
  • Upgrade via the admin dashboard or POST /api/v1/billing/checkout

Tools Are Not Displayed

  • Restart Claude Desktop/Code
  • Check the configuration file for JSON syntax errors
  • Check the logs: ~/Library/Logs/Claude/mcp*.log (macOS)

Further Reading