MCP Server

The Churnkey MCP server (@churnkey/mcp) exposes Churnkey data and operations as Model Context Protocol tools. MCP-aware clients—Claude, Cursor, Claude Code, and others—call these tools to query sessions, payment-recovery analytics, and GDPR endpoints without custom integration code.

The server is open source and authenticates with a Data API key.

Setup

The server runs locally via npx. Configure your MCP client to spawn it on demand and pass credentials through environment variables.

Claude Desktop

Add the following to your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "churnkey": {
      "command": "npx",
      "args": ["-y", "@churnkey/mcp"],
      "env": {
        "CHURNKEY_APP_ID": "your_app_id",
        "CHURNKEY_API_KEY": "live_data_your_key"
      }
    }
  }
}

Fully quit and reopen Claude Desktop.

Claude Code

Register the server with the Claude Code CLI:

claude mcp add churnkey \
  -e CHURNKEY_APP_ID=your_app_id \
  -e CHURNKEY_API_KEY=live_data_your_key \
  -- npx -y @churnkey/mcp

Or configure it in a file. Use ~/.claude.json for a global server (available in every project) or .mcp.json in your project root for a project-scoped server (can be checked into source control):

{
  "mcpServers": {
    "churnkey": {
      "command": "npx",
      "args": ["-y", "@churnkey/mcp"],
      "env": {
        "CHURNKEY_APP_ID": "your_app_id",
        "CHURNKEY_API_KEY": "live_data_your_key"
      }
    }
  }
}

Restart your Claude Code session to load the server.

Cursor

Add the following to ~/.cursor/mcp.json and reload the Cursor window:

{
  "mcpServers": {
    "churnkey": {
      "command": "npx",
      "args": ["-y", "@churnkey/mcp"],
      "env": {
        "CHURNKEY_APP_ID": "your_app_id",
        "CHURNKEY_API_KEY": "live_data_your_key"
      }
    }
  }
}

Other clients

Any MCP client that supports stdio transport works. Spawn npx -y @churnkey/mcp and pass CHURNKEY_APP_ID and CHURNKEY_API_KEY through the environment.

Tools

Tools accept structured input. Filters use enums for known values (saveType, offerType, billingInterval), accept negation through a not object, and accept arrays of dimensions for grouping. The full schema for each tool is exposed through the standard MCP tools/list response.

Data freshness

list_sessions, aggregate_sessions, list_payment_recoveries, and aggregate_payment_recoveries read from the Churnkey analytics warehouse. The warehouse refreshes every 3 hours for sessions and every 20 minutes for payment recoveries. Data more recent than the refresh window does not appear in responses. For real-time reads, query the Data API directly.

dsr_access and dsr_delete read and write the operational store with no lag.

Examples

Sample prompts an MCP client can translate into tool calls:

What was our save rate by month for 2025?

Show the top decline reasons we recovered from last quarter.

Which plans had the most cancellations in March, and what offers were accepted?

Look up all sessions for [email protected].

References

• Source: @churnkey/mcp on GitHub
• Package: @churnkey/mcp on npm