Production Mailchimp MCP Server Starter Template (TypeScript)

Production Mailchimp MCP Server Starter Template (TypeScript)

Overview

This template gives you a fully production-ready Model Context Protocol (MCP) server written in TypeScript that connects Claude Desktop, Cursor, Windsurf, and other MCP-compatible clients to the Mailchimp Marketing API. It uses the stdio transport, meaning the server runs as a local child process launched by the MCP client — no HTTP server, no open ports, no OAuth dance required. Authentication is handled entirely through the MAILCHIMP_API_KEY environment variable that Mailchimp's official Node.js client reads automatically.

The template ships with seven realistic Mailchimp tools covering the most common marketing workflows: listing and inspecting audiences, adding and updating audience members, tagging contacts, listing and creating campaigns, listing templates, and fetching campaign performance reports. Every tool is fully typed with TypeScript, validates its inputs with Zod before touching the network, and returns structured error messages that Claude can reason about rather than raw stack traces.

This is aimed at developers who want to give an AI assistant first-class access to their Mailchimp account for tasks like "add this subscriber to my newsletter audience", "create a draft campaign for our Black Friday sale", or "show me the open rates for our last five sends" — all without leaving the chat interface. The template is equally useful as a learning reference for anyone building their first production MCP server and as a drop-in starting point for a commercial Mailchimp integration.

What You'll Learn

• How to bootstrap an MCP server with the official @modelcontextprotocol/sdk package using StdioServerTransport
• How stdio transport works and why it is the right choice for local, single-user MCP servers
• How to register MCP tools with JSON Schema-compatible input definitions and implement their handlers
• How to authenticate with the Mailchimp Marketing API using an API key and data-centre routing
• How to validate all tool inputs with Zod before making any external API calls
• How to write structured logs with Pino that go to stderr (never stdout) so they never corrupt the stdio MCP frame stream
• How to implement retry logic with exponential back-off for transient Mailchimp API failures
• How to validate required environment variables at startup and exit with a meaningful error if they are missing
• How to write Jest integration tests that invoke MCP tools end-to-end against a mocked Mailchimp client
• How to build a minimal, production-hardened Docker image with a multi-stage Dockerfile
• How to wire up GitHub Actions CI/CD with lint, type-check, test, and Docker build steps
• How to configure Claude Desktop and Cursor to launch and connect to the server

Architecture

Claude Desktop / Cursor / Windsurf
        │  stdin / stdout (JSON-RPC 2.0)
        ▼
  MCP Server Process (Node.js)
        │
   StdioServerTransport
        │
   Tool Router (MCP SDK)
        │
   Zod Input Validation
        │
   Mailchimp API Client (@mailchimp/mailchimp_marketing)
        │  HTTPS
        ▼
  Mailchimp Marketing API (usX.api.mailchimp.com)

The MCP client (Claude Desktop, Cursor, etc.) spawns the server as a child process and communicates over stdin/stdout using JSON-RPC 2.0 framing. The server never binds a TCP port. Pino logs are written exclusively to stderr so they are visible in the MCP client's log viewer without interfering with the protocol stream.

Project Structure

mailchimp-mcp-server/
├── src/
│   ├── __tests__/
│   │   ├── tools/
│   │   │   ├── audiences.test.ts
│   │   │   └── members.test.ts
│   │   ├── config.test.ts
│   │   ├── retry.test.ts
│   │   └── setup-env.ts
│   ├── tools/
│   │   ├── audiences.ts
│   │   ├── campaigns.ts
│   │   ├── members.ts
│   │   ├── reports.ts
│   │   └── templates.ts
│   ├── types/
│   │   └── mailchimp-marketing.d.ts
│   ├── config.ts
│   ├── logger.ts
│   ├── retry.ts
│   └── server.ts
├── .env.example
├── .gitignore
├── eslint.config.mjs
├── jest.config.ts
├── package-lock.json
├── package.json
└── tsconfig.json

Prerequisites

• Node.js 20 or later
• npm 10 or later
• A Mailchimp account with a Marketing API key (generate one here)
• Docker Desktop (optional, for container deployment)
• Claude Desktop or Cursor (to connect the server as an MCP tool provider)

Quick Start

# 1. Clone or copy the template
git clone https://github.com/your-org/mailchimp-mcp-server.git
cd mailchimp-mcp-server

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Edit .env and set MAILCHIMP_API_KEY and MAILCHIMP_SERVER_PREFIX

# 4. Build TypeScript
npm run build

# 5. Run the server (stdio — for manual testing with a pipe)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/server.js

# 6. Run tests
npm test

# 7. (Optional) Start with Docker Compose
docker-compose up --build

Features

• stdio MCP transport — runs as a child process, zero open ports
• Seven Mailchimp tools — audiences, members, tags, campaigns, templates, reports
• Zod input validation — every tool validates inputs before hitting the API
• Environment validation — server exits with a clear error on missing config
• Pino structured logging — JSON logs on stderr, log level controlled by LOG_LEVEL
• Retry with back-off — transient 5xx and rate-limit errors are automatically retried
• Full TypeScript — strict mode, no any, generated declaration files
• Multi-stage Dockerfile — builder + minimal runtime image (~120 MB)
• docker-compose.yml — local development with env file support
• Jest tests — tool execution and error-handling scenarios with mocked Mailchimp client
• GitHub Actions CI — lint, type-check, test, and Docker build on every push
• Claude Desktop config — ready-to-paste mcpServers block
• Cursor config — ready-to-paste .cursor/mcp.json block

Works With

Claude Desktop

Add this block to your claude_desktop_config.json:

{
  "mcpServers": {
    "mailchimp": {
      "command": "node",
      "args": ["/absolute/path/to/mailchimp-mcp-server/dist/server.js"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_SERVER_PREFIX": "us1",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "mailchimp": {
      "command": "node",
      "args": ["/absolute/path/to/mailchimp-mcp-server/dist/server.js"],
      "env": {
        "MAILCHIMP_API_KEY": "your-api-key-here",
        "MAILCHIMP_SERVER_PREFIX": "us1"
      }
    }
  }
}

Configuration

Finding your server prefix: Your Mailchimp API key ends with a data-centre suffix, e.g. abc123def456-us21. The part after the hyphen (us21) is your MAILCHIMP_SERVER_PREFIX.

Deployment

Docker (recommended for production)

# Build the image
docker build -t mailchimp-mcp-server:latest .

# Run interactively (stdio — pipe JSON-RPC frames in)
docker run --rm -i \
  -e MAILCHIMP_API_KEY=your-key-us1 \
  -e MAILCHIMP_SERVER_PREFIX=us1 \
  mailchimp-mcp-server:latest

For Claude Desktop to launch the containerised server, update your mcpServers entry:

{
  "mcpServers": {
    "mailchimp": {
      "command": "docker",
      "args": ["run", "--rm", "-i",
        "-e", "MAILCHIMP_API_KEY=your-key",
        "-e", "MAILCHIMP_SERVER_PREFIX=us1",
        "mailchimp-mcp-server:latest"
      ]
    }
  }
}

docker-compose (local development)

# Copy and fill in .env
cp .env.example .env

# Start
docker-compose up --build

# The container will start and wait on stdin.
# Attach another terminal and pipe frames in, or connect via Claude Desktop.

Running directly with npx / pm2 (server machines)

For headless servers where Claude connects remotely via a wrapper:

# Install globally
npm install -g .

# Run as a long-lived process with pm2
pm2 start dist/server.js --name mailchimp-mcp --no-autorestart

Production Checklist

• MAILCHIMP_API_KEY is stored in a secrets manager (1Password, AWS Secrets Manager, etc.) — never committed to git
• MAILCHIMP_SERVER_PREFIX matches the suffix of your API key
• LOG_LEVEL is set to info or warn in production (not debug or trace)
• API key has the minimum required Mailchimp permissions (see Security Notes below)
• Docker image is built from the production stage (not builder)
• .env is listed in .gitignore and never committed
• npm audit reports zero high/critical vulnerabilities
• All tests pass: npm test
• TypeScript compiles without errors: npm run type-check
• ESLint reports zero errors: npm run lint
• Docker image size is reasonable (docker image ls mailchimp-mcp-server)
• RETRY_MAX_ATTEMPTS and RETRY_BASE_DELAY_MS are tuned for your API usage pattern
• REQUEST_TIMEOUT_MS is set low enough to avoid hanging Claude responses
• GitHub Actions CI passes on the main branch before deploying
• Claude Desktop or Cursor config uses the absolute path to dist/server.js

Security Notes

Least-privilege API key: Create a dedicated Mailchimp API key for this server with the narrowest permissions your use case needs. Mailchimp does not offer scoped API keys for the Marketing API (all Marketing API keys have full account access), so treat the key as a high-value secret:

• Store it in your OS keychain or a secrets manager — never in .env files that are committed
• Rotate the key immediately if it is ever exposed
• Consider creating a separate Mailchimp account/sub-account if you need stronger isolation
• Audit the tools you enable and comment out any tools you do not need to reduce the blast radius of a compromised key

Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

The test suite in src/__tests__/server.test.ts mocks the Mailchimp client at the module level and exercises:

1. Tool list — verifies all seven tools are registered
2. mailchimp_list_audiences — happy path returns formatted audience list
3. mailchimp_get_audience — happy path returns audience detail
4. mailchimp_list_campaigns — happy path returns campaign list
5. mailchimp_create_campaign — happy path creates a campaign and returns its ID
6. mailchimp_list_templates — happy path returns template list
7. mailchimp_get_campaign_report — happy path returns report metrics
8. mailchimp_add_member — happy path subscribes a new member
9. Error handling — Mailchimp API errors are caught and returned as structured error text
10. Zod validation — missing required fields return a validation error, not a 500 typescript utilities mailchimp mailchimp api mailchimp mcp server mcp typescript