Signup Storm MCP Server

A Model Context Protocol (MCP) server for Signup Storm email management system. This MCP server is built on top of the official Signup Storm SDK, providing AI assistants with powerful email signup management capabilities.

Features

Core SDK Features

• Email Signup Management - Subscribe emails with full attribution tracking
• Unsubscribe Management - Handle unsubscribes from specific lists or globally
• Subscriber Status - Check subscription status and history
• UTM Attribution - Automatic UTM parameter capture and tracking
• Custom Fields - Store additional subscriber data
• GDPR Compliance - Handle consent tracking and timestamps

MCP-Specific Analytics

• Signup Statistics - Get analytics for date ranges, sites, or lists
• Contact Management - List, search, and filter contacts
• List Management - Create and manage email lists
• Data Export - Export contacts, events, and subscriptions in JSON/CSV
• Bulk Operations - Manage subscriptions at scale

Documentation & Integration Help

• Framework Integration Docs - Get comprehensive integration examples
• SDK Usage Examples - Framework-specific code samples
• Setup Guides - Environment configuration and best practices

Installation

Global Installation

npm install -g @signup-storm/mcp-server

Local Development

git clone <repository>
cd packages/mcp-client
pnpm install
pnpm build

Configuration

Set the following environment variables:

# Required: Your Signup Samurai API key
export SIGNUP_SAMURAI_API_KEY="your-api-key-here"

# Optional: Base URL (defaults to http://localhost:3000)
export SIGNUP_SAMURAI_BASE_URL="https://your-signup-samurai-instance.com"

# Optional: Enable debug mode
export NODE_ENV="development"

Usage with Claude Desktop

Add to your Claude Desktop MCP configuration:

{
  "mcpServers": {
    "signup-samurai": {
      "command": "signup-samurai-mcp",
      "env": {
        "SIGNUP_SAMURAI_API_KEY": "your-api-key-here",
        "SIGNUP_SAMURAI_BASE_URL": "https://your-instance.com"
      }
    }
  }
}

Available Tools

Core Signup Management

signup

Subscribe an email address to a list with full attribution tracking.

{
  email: "[email protected]",
  list: "newsletter",
  tags: ["landing-page", "early-access"],
  utm: {
    source: "twitter",
    medium: "social",
    campaign: "product-launch"
  },
  customFields: {
    firstName: "John",
    company: "Acme Corp"
  },
  pageUrl: "https://example.com/signup",
  gdprConsent: true
}

unsubscribe

Unsubscribe an email from a specific list or globally.

{
  email: "[email protected]",
  list: "newsletter", // Optional - omit for global unsubscribe
  reason: "No longer interested"
}

get_subscriber_status

Check the subscription status of an email address.

{
  email: "[email protected]"
}

Analytics & Management

signup_stats

Get signup statistics and analytics.

{
  dateFrom: "2025-01-01",
  dateTo: "2025-01-31",
  listSlug: "newsletter",
  siteId: "main-site"
}

list_contacts

List and search contacts with filtering.

{
  page: 1,
  limit: 50,
  search: "john@",
  status: "SUBSCRIBED",
  listSlug: "newsletter",
  tags: ["vip", "early-access"]
}

get_lists

Get all email lists, optionally filtered by site.

{
  siteId: "main-site" // Optional
}

create_list

Create a new email list.

{
  name: "Product Updates",
  slug: "product-updates",
  description: "Updates about our product releases",
  siteId: "main-site" // Optional
}

manage_subscription

Subscribe or unsubscribe a contact (alternative to direct signup/unsubscribe).

{
  email: "[email protected]",
  listSlug: "newsletter",
  action: "subscribe", // or "unsubscribe"
  tags: ["manual-add"]
}

export_data

Export contacts, events, or subscriptions data.

{
  type: "contacts", // or "events", "subscriptions"
  format: "json", // or "csv"
  listSlug: "newsletter",
  dateFrom: "2025-01-01",
  dateTo: "2025-01-31",
  limit: 1000
}

Example AI Conversations

Subscribe a User

"Subscribe [email protected] to the newsletter list with tags 'vip' and 'early-access'"

The AI will use the signup tool to add the subscriber with proper attribution.

Check Subscription Status

"What's the subscription status of [email protected]?"

The AI will use get_subscriber_status to check the user's current status across all lists.

Get Analytics

"Show me signup statistics for the newsletter list in January 2025"

The AI will use signup_stats with appropriate date filters.

Export Data

"Export all contacts from the newsletter list as CSV"

The AI will use export_data to generate a CSV export.

Documentation & Integration Help

get_integration_docs

Get framework-specific integration documentation and examples.

{
  framework: "nextjs", // "nextjs", "react-router", "astro", "react", "vanilla", "overview"
  section: "all" // "installation", "basic-usage", "advanced", "server-side", "troubleshooting", "all"
}

Example Usage:

• "Show me Next.js integration examples" → The AI will use get_integration_docs with framework: "nextjs"
• "How do I integrate with React Router v7?" → The AI will use get_integration_docs with framework: "react-router"
• "Give me a vanilla JavaScript example" → The AI will use get_integration_docs with framework: "vanilla"

SDK Integration

This MCP server is built on top of the official Signup Samurai SDK (@signup-samurai/sdk), which provides:

• Type Safety - Full TypeScript support with comprehensive types
• Error Handling - Structured error responses with proper error codes
• Validation - Input validation using Zod schemas
• Attribution - Automatic UTM parameter capture and enrichment
• Event System - Event listeners for signup success/error tracking
• Browser Support - Works in both Node.js and browser environments

Development

Building

pnpm build

Running in Development

pnpm dev

Testing

# Test with a simple MCP client
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/server.js

Architecture

MCP Client
├── SignupSamuraiMCPAPI (extends SignupSamurai SDK)
│   ├── Core SDK methods (signup, unsubscribe, getSubscriberStatus)
│   └── MCP-specific methods (getStats, getContacts, exportData)
├── Tool Handlers
│   ├── Input validation (Zod schemas)
│   ├── API calls via SDK
│   └── Response formatting
└── MCP Server
    ├── Tool registration
    ├── Request handling
    └── Error management

Error Handling

The MCP server provides structured error responses:

{
  "content": [
    {
      "type": "text",
      "text": "Error: VALIDATION_ERROR - Email is required"
    }
  ],
  "isError": true
}

Common error codes:

• VALIDATION_ERROR - Invalid input parameters
• NETWORK_ERROR - Connection or timeout issues
• HTTP_ERROR - API server errors
• ALREADY_SUBSCRIBED - Email already subscribed to list

Version History

v2.0.0

• SDK Integration - Now built on official Signup Samurai SDK
• Enhanced Tools - Added signup, unsubscribe, and get_subscriber_status
• Better Error Handling - Structured errors with proper codes
• Type Safety - Full TypeScript support throughout
• Attribution Tracking - Automatic UTM capture and enrichment

v1.0.0

• Initial MCP server implementation
• Basic analytics and management tools

License

MIT License - see LICENSE file for details.