---
title: MCP Server
description: Connect Claude, Cursor, and other AI agents to your Churnkey data.
---

The Churnkey MCP server (`@churnkey/mcp`) exposes Churnkey data and operations as [Model Context Protocol](https://modelcontextprotocol.io) 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](/data-integrations/data-api).

## Setup

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

::alert{type="info" emoji="🔑"}
Get your **App ID** and **Data API Key** from [Churnkey → Settings → Organization](https://app.churnkey.co/settings/organization). Live keys begin with `live_data_`; test keys begin with `test_data_`.
::

### 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`

```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:

```bash
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):

```json
{
  "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:

```json
{
  "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

| Tool | Description |
|------|-------------|
| `list_sessions` | Returns cancel and dunning sessions, filterable by date range, customer, outcome, plan, segment, A/B test, and more. Up to 500 sessions per call. |
| `aggregate_sessions` | Returns session counts grouped by one or more dimensions (`saveType`, `offerType`, `month`, `planId`, others). |
| `list_payment_recoveries` | Returns individual failed-payment recovery campaigns. |
| `aggregate_payment_recoveries` | Returns counts and amounts (invoice, recovered, pending, lost) for failed-payment recoveries, in original currency and USD. |
| `dsr_access` | GDPR/CCPA right-to-know lookup by email. |
| `dsr_delete` | GDPR/CCPA right-to-delete. Destructive; clients prompt for confirmation. |

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](/data-integrations/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 `customer@example.com`.

## References

- Source: [`@churnkey/mcp` on GitHub](https://github.com/churnkey/sdk/tree/main/packages/mcp)
- Package: [`@churnkey/mcp` on npm](https://www.npmjs.com/package/@churnkey/mcp)