@dancumberland/kit-mcp

Agent-optimized MCP server for Kit.com (formerly ConvertKit) email marketing. 13 composite tools covering 100% of the Kit V4 API with formatted responses, rate limiting, and typed errors.

Quick Start

1. Get your Kit API key from kit.com → Account Settings → Developer

2. Open Claude Desktop → Settings → Developer → Edit Config

3. Add to claude_desktop_config.json:

{
  "mcpServers": {
    "kit": {
      "command": "npx",
      "args": ["-y", "@dancumberland/kit-mcp@latest"],
      "env": {
        "KIT_API_KEY": "your-key-here"
      }
    }
  }
}

4. Restart Claude Desktop. Say "Test my Kit connection" to verify.

Tools

Usage Examples

Find a subscriber and their tags:

Use manage_subscribers with action "find" and email "dan@example.com"

Response (~80 tokens):

Subscriber: Dan Cumberland (dan@example.com)
ID: 123 | State: active | Created: 2024-01-15
Tags: ai-strategy, newsletter
Custom fields: role=executive, company=Acme

Create a broadcast draft:

Use manage_broadcasts with action "create", subject "March Newsletter", and content "<p>Hello!</p>"

Response:

Broadcast created (ID: 42): "March Newsletter" — saved as draft

Tag a subscriber:

Use manage_tags with action "tag_subscriber", tag_id 5, and email "dan@example.com"

Response:

Tag 5 applied to dan@example.com.

View broadcast performance:

Use manage_broadcasts with action "stats" and id 42

Response:

Broadcast: "March Newsletter"
Status: completed | Recipients: 11,234

Performance:
  Open rate: 43.5%
  Click rate: 11.0%
  Unsubscribes: 23
  Total clicks: 1,234

Why Composite Tools?

Most MCP servers expose one tool per API endpoint (29+ tools for Kit). This causes:

• Context bloat — ~8,000+ tokens just for tool definitions

• Poor agent accuracy — selection degrades beyond 20 tools

• Cursor incompatibility — hard limit of 40 tools across all servers

Our 13 composite tools use a discriminated union action parameter. The agent picks the resource, then specifies the operation:

Authentication

API Key (default): Set KIT_API_KEY environment variable. Covers all endpoints except purchases and bulk operations.

{
  "env": {
    "KIT_API_KEY": "your-api-key"
  }
}

OAuth (optional): Set KIT_OAUTH_TOKEN for manage_purchases and bulk_operations.

{
  "env": {
    "KIT_API_KEY": "your-api-key",
    "KIT_OAUTH_TOKEN": "your-oauth-token"
  }
}

Rate limits are enforced automatically: 120 req/min (API key) or 600 req/min (OAuth).

Error Handling

Every error includes a recovery hint the agent can act on:

Error 401: Invalid API key
Recovery: Check your KIT_API_KEY environment variable. Find your key at kit.com → Account Settings → Developer.

Error 429: Rate limit exceeded
Recovery: Wait 60 seconds before retrying. Current usage has hit the per-minute cap.

Error 403: bulk_operations requires OAuth authentication
Recovery: Set KIT_OAUTH_TOKEN environment variable. See README for OAuth setup guide.

Automatic retry: 429 errors retry up to 3 times with exponential backoff (1s, 2s, 4s). 5xx errors retry once after 1s. 422 validation errors never retry.

Development

npm install
npm run dev          # Watch mode
npm run build        # Production build
npm test             # Unit tests (140 tests)
npm run test:int     # Integration tests (requires KIT_API_KEY)
npm run lint         # Biome check
npm run typecheck    # TypeScript check

Tech Stack

• TypeScript — strict mode, zero any types

• MCP SDK — @modelcontextprotocol/sdk

• Zod — discriminated union input validation

• Native fetch — no axios/got/node-fetch

• tsup — ESM build with shebang

• Vitest — unit + integration tests

• Biome — linting + formatting

License

MIT