> For the complete documentation index, see [llms.txt](https://developer.paddle.com/llms.txt).

# Paddle MCP server

Give AI agents access to your Paddle account so they can read data and take actions across pricing, billing, and integration workflows.

---

The [Paddle MCP server](https://github.com/PaddleHQ/paddle-mcp-server) lets AI agents interact with your Paddle account. Instead of navigating the dashboard or making API calls, you can ask an agent in natural language to handle pricing, billing, support, and integration workflows.

{% callout type="warning" title="AI agents can make mistakes" %}
The Paddle MCP server has access to the data in your account. Review every action the agent takes before and after execution.
{% /callout %}

## How it works

The Paddle MCP server connects AI agents to your Paddle account so they can:

- Build and evolve your pricing model, including regional pricing and migrations.
- Investigate failed payments and resolve billing issues.
- Generate reports and analyze revenue, refunds, and transaction patterns.
- Process subscription upgrades, downgrades, pauses, and cancellations.
- Onboard enterprise customers with custom pricing and manual invoicing.
- Generate integration code, configure webhooks, and simulate events for testing.

{% callout type="note" %}
The Paddle MCP server lets your agent take actions in your account. To give your agent up-to-date knowledge of Paddle, set up the [docs MCP server](https://developer.paddle.com/sdks/ai/docs-mcp.md).
{% /callout %}

## Available tools

The Paddle MCP server exposes the full Paddle API, so your agent can perform any action you can perform using the API.

You scope the tools available to the agent at install time using the `--tools` flag:

| Value                       | What it exposes                                                              |
| --------------------------- | ---------------------------------------------------------------------------- |
| `all`                       | Every tool, including destructive actions like update and archive.           |
| `non-destructive`           | Read plus safe writes (create, preview). Excludes updates and archives.      |
| `read-only`                 | Read-only tools. Safest default while evaluating or debugging.               |
| `tool_a,tool_b,...`         | Comma-separated list of specific tool names.                                 |

We recommend starting with `read-only` or `non-destructive` while you get comfortable with the server, then widen as needed.

## Before you begin

[Create an API key](https://developer.paddle.com/api-reference/about/api-keys#create-api-key.md) with the [permissions](https://developer.paddle.com/api-reference/about/permissions.md) needed for the tools you plan to use.

## Install the MCP server

The server uses [stdio transport](https://modelcontextprotocol.io/specification/2024-11-05/basic/transports#stdio) and runs locally. Setup varies slightly across clients.

{% callout type="info" %}
Assistants using the MCP server can read and change data in your Paddle account. Only use agents that you trust.
{% /callout %}

{% tabs %}
{% tab-item title="Claude Desktop" %}

1. Open Claude Desktop and go to **Settings > Developer > Edit Config**.
2. Add the `paddle` server to the `mcpServers` object.
3. Replace `YOUR_API_KEY`, set `--environment` to `sandbox` or `production`, and set `--tools` to your preferred scope.
4. Save the file and restart Claude Desktop.

```json
{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": [
        "-y",
        "@paddle/paddle-mcp",
        "--api-key=YOUR_API_KEY",
        "--environment=sandbox",
        "--tools=non-destructive"
      ]
    }
  }
}
```

{% /tab-item %}

{% tab-item title="Claude Code" %}

Run the following command, replacing `YOUR_API_KEY` and setting the environment and tool scope:

```bash
claude mcp add paddle -- npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive
```

{% /tab-item %}

{% tab-item title="OpenAI Codex" %}

Run the following command in your terminal:

```bash
codex mcp add paddle npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive
```

{% /tab-item %}

{% tab-item title="Cursor" %}

### One-click install

[Install the Paddle MCP server in Cursor](https://cursor.com/en-US/install-mcp?name=paddle&config=eyJlbnYiOnsiUEFERExFX0FQSV9LRVkiOiJ5b3VyX2FwaV9rZXkiLCJQQURETEVfRU5WSVJPTk1FTlQiOiJzYW5kYm94IiwiUEFERExFX01DUF9UT09MUyI6Im5vbi1kZXN0cnVjdGl2ZSJ9LCJjb21tYW5kIjoibnB4IC15IEBwYWRkbGUvcGFkZGxlLW1jcCJ9)

After installing, replace `PADDLE_API_KEY`, set `PADDLE_ENVIRONMENT`, and set `PADDLE_MCP_TOOLS` before clicking Install.

### Manual install

1. Open **Cursor Settings > MCP Tools** (or Command/Ctrl + Shift + J > **MCP Tools**).
2. Click Add Custom MCP.
3. Add the `paddle` server configuration and save.

```json
{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": [
        "-y",
        "@paddle/paddle-mcp",
        "--api-key=YOUR_API_KEY",
        "--environment=sandbox",
        "--tools=non-destructive"
      ]
    }
  }
}
```

{% /tab-item %}

{% tab-item title="VS Code" %}

### One-click install

[Install the Paddle MCP server in VS Code](vscode:mcp/install?%7B%22name%22%3A%22paddle%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40paddle%2Fpaddle-mcp%22%5D%2C%22env%22%3A%7B%22PADDLE_API_KEY%22%3A%22your-api-key%22%2C%22PADDLE_ENVIRONMENT%22%3A%22sandbox%22%2C%22PADDLE_MCP_TOOLS%22%3A%22non-destructive%22%7D%7D)

After installing, replace `PADDLE_API_KEY`, set `PADDLE_ENVIRONMENT`, and set `PADDLE_MCP_TOOLS`.

### Manual install

1. Press Command/Ctrl + Shift + P.
2. Run MCP: Add Server....
3. Enter `npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive`.
4. Click User Settings and restart VS Code.

{% /tab-item %}

{% tab-item title="Raycast" %}

[Install the Paddle MCP server in Raycast](raycast://mcp/install?%7B%22name%22%3A%22paddle%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40paddle%2Fpaddle-mcp%22%5D%2C%22env%22%3A%7B%22PADDLE_API_KEY%22%3A%22your-api-key%22%2C%22PADDLE_ENVIRONMENT%22%3A%22sandbox%22%2C%22PADDLE_MCP_TOOLS%22%3A%22non-destructive%22%7D%7D)

After installing, replace `PADDLE_API_KEY`, set `PADDLE_ENVIRONMENT`, and set `PADDLE_MCP_TOOLS`.

{% /tab-item %}

{% tab-item title="Other" %}

For any other MCP-compatible client, use the following command:

```bash
npx -y @paddle/paddle-mcp --api-key=YOUR_API_KEY --environment=sandbox --tools=non-destructive
```

{% /tab-item %}
{% /tabs %}

## Use the server

Once installed, tools are registered and available for the agent to use. Some clients prompt before running each tool.

{% callout type="danger" %}
If you enable `--dangerously-skip-permissions` or similar setting in your client, your agent can run tools without your approval. This includes using the Paddle MCP server.
{% /callout %}

## Example prompts

Use these example prompts to get started.

### Manage your pricing

Describe your pricing structure to the agent — tiers, billing cycles, trial periods, regional overrides — and let it create the products and prices. For migrations, walk through old plans, grandfather pricing, and archiving the old catalog step by step.

```markdown {% wrap=true %}
Set up three subscription plans for my collaboration SaaS: Basic at $29/mo or $290/yr (14-day trial), Pro at $79/mo or $790/yr (14-day trial), Advanced at $299/mo or $2,990/yr (14-day trial). Also add a seats add-on at $10/seat/month or $100/seat/year, quantity 1-1000. After you create everything, show me the products and prices in a markdown table.
```

### Debug and resolve billing issues

Give the agent a customer email or ID, a time range, and the issue to investigate. It can check subscription history, payment attempts, adjustments, and scheduled changes, then recommend or execute a fix.

```markdown {% wrap=true %}
Investigate the failed payment for sarah@example.com. Think step-by-step: when it failed, whether it's recurring, what plan they're on, whether there are scheduled changes, and details of the payment method. If you find multiple failures, check whether other subscriptions for this customer show the same pattern.
```

### Understand company performance

Ask the agent to generate a [report](https://developer.paddle.com/build/reports/generate-reports.md) and analyze it. Reports arrive as CSV files — the agent can retrieve them with the `get_report_csv` tool once ready.

```markdown {% wrap=true %}
Generate a transaction_line_items report for the past 6 months, filtered for completed and canceled statuses across all currencies. Identify our three highest- and lowest-revenue product/price combinations, flag pricing anomalies across regions, and recommend adjustments.
```

### Handle subscription and lifecycle changes

For upgrades, downgrades, pauses, or cancellations, always ask for a preview first (`preview_subscription_update`) so you see the financial impact before the change is applied.

```markdown {% wrap=true %}
Customer john@startup.com wants to upgrade from Basic ($29/mo) to Pro ($79/mo) immediately. Preview the change, show me the current and new amounts plus any proration, then wait for my approval before executing.
```

### Onboard enterprise customers

Paste the quote or contract details, include tax ID and billing contacts, and ask the agent to create custom pricing, configure manual invoicing, and preview the first invoice before execution.

```markdown {% wrap=true %}
Set up Example Inc. as an enterprise customer: 100 licenses at $45/user/month billed annually in USD, plus a $6,000/year Premium Support flat fee. Billing contact bob@example.com, tax ID 12-3456789, address 123 Business Park, New York, NY 10001. Preview the full transaction before creating anything.
```

### Integrate and test Paddle

Use the agent to scaffold integration code, configure notification destinations, and simulate webhook events end to end.

```markdown {% wrap=true %}
Create a notification destination for my Next.js webhook endpoint at https://example.com/api/webhooks, subscribed to subscription.created, subscription.updated, and transaction.completed. Then simulate a subscription.created event so I can verify my handler.
```

## Best practices

- **Mention Paddle explicitly.**
  "Find a customer in Paddle" is less ambiguous than "find a customer."
- **Provide all the context.**
  Customer IDs, time ranges, currencies — pass them in rather than letting the agent guess.
- **Ask for a plan first.**
  For complex work, get the agent to draft a plan before executing. Approve or edit, then run.
- **State your goal.**
  Tell the agent what success looks like and what format you want the output in.
- **Iterate.**  
  If the first response misses, refine the prompt rather than starting over.