Paddle Billing

Interaja com a API do Paddle Billing para gerenciar produtos, preços, clientes, transações e assinaturas.

Documentação

Servidor MCP para Paddle Billing

Paddle Billing é o merchant of record voltado para desenvolvedores. Cuidamos de pagamentos, impostos, assinaturas e métricas com uma API unificada que faz tudo.

Este é um servidor Model Context Protocol (MCP) que fornece a LLMs e agentes de IA ferramentas para interagir com a API da Paddle.

Importante: Este servidor MCP funciona com Paddle Billing. Ele não suporta Paddle Classic. Para trabalhar com Paddle Classic, consulte: Referência da API Paddle Classic

Recursos

O servidor MCP tem paridade quase total com a API da Paddle, permitindo que assistentes de IA e agentes possam:

Gerenciar todo o seu catálogo Paddle
Visualizar informações de clientes, compras e provisionamento
Lidar com fluxos de trabalho de assinaturas, pagamentos e reembolsos
Depurar problemas de cobrança e gerenciamento de pedidos
Criar e ajustar transações diretamente na conversa
Gerar relatórios financeiros para insights financeiros e operacionais
Implementar e testar integrações Paddle mais rapidamente

Ferramentas disponíveis

O servidor MCP pode usar as seguintes ferramentas para realizar ações com sua conta Paddle:

Produtos

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar produtos	`list_products`	✅	✅
Criar um produto	`create_product`	✅	❌
Obter um produto	`get_product`	✅	✅
Atualizar um produto	`update_product`	❌	❌

Preços

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar preços	`list_prices`	✅	✅
Criar um preço	`create_price`	✅	❌
Obter um preço	`get_price`	✅	✅
Atualizar um preço	`update_price`	❌	❌
Visualizar preços	`preview_prices`	✅	❌

Descontos

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar descontos	`list_discounts`	✅	✅
Criar um desconto	`create_discount`	✅	❌
Obter um desconto	`get_discount`	✅	✅
Atualizar um desconto	`update_discount`	❌	❌

Grupos de Descontos

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar grupos de descontos	`list_discount_groups`	✅	✅
Criar um grupo de descontos	`create_discount_group`	✅	❌
Obter um grupo de descontos	`get_discount_group`	✅	✅
Atualizar um grupo de descontos	`update_discount_group`	❌	❌
Arquivar um grupo de descontos	`archive_discount_group`	❌	❌

Clientes

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar clientes	`list_customers`	✅	✅
Criar um cliente	`create_customer`	✅	❌
Obter um cliente	`get_customer`	✅	✅
Atualizar um cliente	`update_customer`	❌	❌
Listar saldos de crédito de um cliente	`list_credit_balances`	✅	✅

Endereços

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar endereços de um cliente	`list_addresses`	✅	✅
Criar um endereço para um cliente	`create_address`	✅	❌
Obter um endereço de um cliente	`get_address`	✅	✅
Atualizar um endereço de um cliente	`update_address`	❌	❌

Empresas

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar empresas de um cliente	`list_businesses`	✅	✅
Criar uma empresa para um cliente	`create_business`	✅	❌
Obter uma empresa de um cliente	`get_business`	✅	✅
Atualizar uma empresa de um cliente	`update_business`	❌	❌

Transações

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar transações	`list_transactions`	✅	✅
Criar uma transação	`create_transaction`	✅	❌
Obter uma transação	`get_transaction`	✅	✅
Atualizar uma transação	`update_transaction`	❌	❌
Visualizar uma transação	`preview_transaction_create`	✅	❌
Revisar informações do cliente em uma transação faturada ou concluída	`revise_transaction`	❌	❌
Obter uma fatura em PDF de uma transação	`get_transaction_invoice`	✅	✅

Ajustes

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar ajustes	`list_adjustments`	✅	✅
Criar um ajuste	`create_adjustment`	✅	❌
Obter uma nota de crédito em PDF de um ajuste	`get_adjustment_credit_note`	✅	✅

Assinaturas

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar assinaturas	`list_subscriptions`	✅	✅
Obter uma assinatura	`get_subscription`	✅	✅
Atualizar uma assinatura	`update_subscription`	❌	❌
Cancelar uma assinatura	`cancel_subscription`	❌	❌
Pausar uma assinatura	`pause_subscription`	❌	❌
Retomar uma assinatura pausada	`resume_subscription`	❌	❌
Ativar uma assinatura em teste	`activate_subscription`	❌	❌
Visualizar uma atualização de assinatura	`preview_subscription_update`	✅	❌
Criar uma cobrança única para uma assinatura	`create_subscription_charge`	✅	❌
Visualizar uma cobrança única para uma assinatura	`preview_subscription_charge`	✅	❌

Métodos de Pagamento Salvos

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar métodos de pagamento salvos de um cliente	`list_saved_payment_methods`	✅	✅
Obter um método de pagamento salvo de um cliente	`get_saved_payment_method`	✅	✅
Excluir um método de pagamento salvo de um cliente	`delete_saved_payment_method`	❌	❌

Sessões do Portal do Cliente

Operação	Ferramenta	Não destrutiva	Somente leitura
Criar uma sessão do portal do cliente	`create_customer_portal_session`	✅	❌

Configurações de Notificação

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar configurações de notificação	`list_notification_settings`	✅	✅
Criar uma configuração de notificação	`create_notification_setting`	✅	❌
Obter uma configuração de notificação	`get_notification_setting`	✅	✅
Atualizar uma configuração de notificação	`update_notification_setting`	❌	❌
Excluir uma configuração de notificação	`delete_notification_setting`	❌	❌

Eventos

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar eventos	`list_events`	✅	✅

Notificações

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar notificações	`list_notifications`	✅	✅
Obter uma notificação	`get_notification`	✅	✅
Reproduzir uma notificação	`replay_notification`	✅	❌

Logs de Notificação

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar logs de uma notificação	`list_notification_logs`	✅	✅

Simulações

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar simulações	`list_simulations`	✅	✅
Criar uma simulação	`create_simulation`	✅	❌
Obter uma simulação	`get_simulation`	✅	✅
Atualizar uma simulação	`update_simulation`	❌	❌

Execuções de Simulação

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar execuções de uma simulação	`list_simulation_runs`	✅	✅
Criar uma execução para uma simulação	`create_simulation_run`	✅	❌
Obter uma execução de uma simulação	`get_simulation_run`	✅	✅

Eventos de Execução de Simulação

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar eventos de uma execução de simulação	`list_simulation_run_events`	✅	✅
Obter um evento de uma execução de simulação	`get_simulation_run_event`	✅	✅
Reproduzir um evento de uma execução de simulação	`replay_simulation_run_event`	✅	❌

Relatórios

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar relatórios	`list_reports`	✅	✅
Criar um relatório	`create_report`	✅	❌
Obter um relatório	`get_report`	✅	✅
Obter um arquivo CSV de um relatório	`get_report_csv`	✅	✅

Tokens do Lado do Cliente

Operação	Ferramenta	Não destrutiva	Somente leitura
Listar tokens do lado do cliente	`list_client_side_tokens`	✅	✅
Criar um token do lado do cliente	`create_client_side_token`	✅	❌
Obter um token do lado do cliente	`get_client_side_token`	✅	✅
Revogar um token do lado do cliente	`revoke_client_side_token`	❌	❌

Instalação

Para usar o servidor MCP, você precisará de uma chave de API. Você pode criar e gerenciar chaves de API em Paddle > Ferramentas de desenvolvedor > Autenticação:

Sandbox: https://sandbox-vendors.paddle.com/authentication-v2
Produção: https://vendors.paddle.com/authentication-v2

Adicionar o seguinte ao seu arquivo de configurações MCP configurará e executará o servidor MCP Paddle em um cliente como Claude Desktop, Cursor ou Windsurf:

Método 1: Instalação com um clique no Cursor ou VS Code

Você pode instalar o servidor MCP Paddle com um único clique no Cursor ou VS Code.

Após a instalação, você precisará atualizar a configuração no seu arquivo de configurações MCP para substituir your_api_key pela sua chave de API Paddle real e ajustar os valores de ambiente e ferramentas conforme necessário.

Método 2: Usando argumentos de linha de comando (Recomendado para `npx`)

Adicione o seguinte ao arquivo de configurações ou de configuração MCP no cliente que você está usando:

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

Substitua your_api_key pela sua chave de API Paddle real, defina --environment como sandbox ou production, e defina --tools para as ferramentas que você deseja carregar e disponibilizar para o cliente MCP.

Método 3: Usando variáveis de ambiente

Adicione o seguinte ao arquivo de configurações ou de configuração MCP no cliente que você está usando:

{
  "mcpServers": {
    "paddle": {
      "command": "npx",
      "args": ["-y", "@paddle/paddle-mcp"],
      "env": {
        "PADDLE_API_KEY": "your_api_key",
        "PADDLE_ENVIRONMENT": "sandbox",
        "PADDLE_MCP_TOOLS": "non-destructive"
      }
    }
  }
}

Substitua your_api_key pela sua chave de API Paddle real, defina PADDLE_ENVIRONMENT como sandbox ou production, e defina PADDLE_MCP_TOOLS para as ferramentas que você deseja carregar e disponibilizar para o cliente MCP.

Filtrando ferramentas

Você pode filtrar quais ferramentas são carregadas e disponibilizadas para o cliente MCP passando o argumento --tools (Método 2) ou definindo a variável de ambiente PADDLE_MCP_TOOLS (Método 1 ou 3). Os valores aceitos são:

all - Todas as ferramentas estão disponíveis
read-only - Apenas operações de leitura estão disponíveis
non-destructive - Operações de leitura e operações de escrita seguras estão disponíveis (padrão)
Uma lista separada por vírgulas de nomes específicos de ferramentas (por exemplo, list_products,get_product,create_product)

Para guias de configuração detalhados, consulte:

Desenvolvimento

Instale as dependências:
```
pnpm install
```
Compile o servidor:
```
pnpm build
```
Atualize o cliente para usar a compilação local:
```
{
  "mcpServers": {
    "paddle": {
      "command": "node",
      "args": ["path/to/paddle-mcp-server/build/index.js"],
      "env": {
        "PADDLE_API_KEY": "your_api_key",
        "PADDLE_ENVIRONMENT": "sandbox",
        "PADDLE_MCP_TOOLS": "all"
      }
    }
  }
}
```
A variável de ambiente PADDLE_MCP_TOOLS aceita os mesmos valores que o argumento --tools: all, read-only, non-destructive, ou uma lista separada por vírgulas de nomes de ferramentas. Se não for definida, o padrão é non-destructive.

Depuração

Para depurar o servidor MCP, você pode usar a ferramenta MCP Inspector:

Execute o servidor com o inspector:
```
pnpm inspector
```
Abra a URL fornecida no seu navegador para visualizar e depurar as solicitações e respostas do MCP.
Inclua os argumentos --api-key e --environment.