Paddle Billing

Interactúa con la API de Paddle Billing para gestionar productos, precios, clientes, transacciones y suscripciones.

Documentación

Servidor MCP para Paddle Billing

Paddle Billing es el merchant of record orientado a desarrolladores. Nos encargamos de pagos, impuestos, suscripciones y métricas con una API unificada que lo hace todo.

Este es un servidor de Model Context Protocol (MCP) que proporciona a los LLM y agentes de IA herramientas para interactuar con la API de Paddle.

Importante: Este servidor MCP funciona con Paddle Billing. No es compatible con Paddle Classic. Para trabajar con Paddle Classic, consulta: Referencia de la API de Paddle Classic

Características

El servidor MCP tiene una paridad casi total con la API de Paddle, lo que permite a los asistentes de IA y agentes:

Gestionar todo tu catálogo de Paddle
Consultar información de clientes, compras y aprovisionamiento
Gestionar flujos de trabajo de suscripciones, pagos y reembolsos
Depurar problemas de facturación y gestión de pedidos
Crear y ajustar transacciones directamente en la conversación
Generar informes financieros para obtener información financiera y operativa
Implementar y probar integraciones de Paddle más rápido

Herramientas disponibles

El servidor MCP puede usar las siguientes herramientas para realizar acciones con tu cuenta de Paddle:

Productos

Operación	Herramienta	No destructiva	Solo lectura
Listar productos	`list_products`	✅	✅
Crear un producto	`create_product`	✅	❌
Obtener un producto	`get_product`	✅	✅
Actualizar un producto	`update_product`	❌	❌

Precios

Operación	Herramienta	No destructiva	Solo lectura
Listar precios	`list_prices`	✅	✅
Crear un precio	`create_price`	✅	❌
Obtener un precio	`get_price`	✅	✅
Actualizar un precio	`update_price`	❌	❌
Previsualizar precios	`preview_prices`	✅	❌

Descuentos

Operación	Herramienta	No destructiva	Solo lectura
Listar descuentos	`list_discounts`	✅	✅
Crear un descuento	`create_discount`	✅	❌
Obtener un descuento	`get_discount`	✅	✅
Actualizar un descuento	`update_discount`	❌	❌

Grupos de descuentos

Operación	Herramienta	No destructiva	Solo lectura
Listar grupos de descuentos	`list_discount_groups`	✅	✅
Crear un grupo de descuentos	`create_discount_group`	✅	❌
Obtener un grupo de descuentos	`get_discount_group`	✅	✅
Actualizar un grupo de descuentos	`update_discount_group`	❌	❌
Archivar un grupo de descuentos	`archive_discount_group`	❌	❌

Clientes

Operación	Herramienta	No destructiva	Solo lectura
Listar clientes	`list_customers`	✅	✅
Crear un cliente	`create_customer`	✅	❌
Obtener un cliente	`get_customer`	✅	✅
Actualizar un cliente	`update_customer`	❌	❌
Listar saldos de crédito de un cliente	`list_credit_balances`	✅	✅

Direcciones

Operación	Herramienta	No destructiva	Solo lectura
Listar direcciones de un cliente	`list_addresses`	✅	✅
Crear una dirección para un cliente	`create_address`	✅	❌
Obtener una dirección de un cliente	`get_address`	✅	✅
Actualizar una dirección de un cliente	`update_address`	❌	❌

Empresas

Operación	Herramienta	No destructiva	Solo lectura
Listar empresas de un cliente	`list_businesses`	✅	✅
Crear una empresa para un cliente	`create_business`	✅	❌
Obtener una empresa de un cliente	`get_business`	✅	✅
Actualizar una empresa de un cliente	`update_business`	❌	❌

Transacciones

Operación	Herramienta	No destructiva	Solo lectura
Listar transacciones	`list_transactions`	✅	✅
Crear una transacción	`create_transaction`	✅	❌
Obtener una transacción	`get_transaction`	✅	✅
Actualizar una transacción	`update_transaction`	❌	❌
Previsualizar una transacción	`preview_transaction_create`	✅	❌
Revisar la información del cliente en una transacción facturada o completada	`revise_transaction`	❌	❌
Obtener una factura en PDF de una transacción	`get_transaction_invoice`	✅	✅

Ajustes

Operación	Herramienta	No destructiva	Solo lectura
Listar ajustes	`list_adjustments`	✅	✅
Crear un ajuste	`create_adjustment`	✅	❌
Obtener una nota de crédito en PDF de un ajuste	`get_adjustment_credit_note`	✅	✅

Suscripciones

Operación	Herramienta	No destructiva	Solo lectura
Listar suscripciones	`list_subscriptions`	✅	✅
Obtener una suscripción	`get_subscription`	✅	✅
Actualizar una suscripción	`update_subscription`	❌	❌
Cancelar una suscripción	`cancel_subscription`	❌	❌
Pausar una suscripción	`pause_subscription`	❌	❌
Reanudar una suscripción pausada	`resume_subscription`	❌	❌
Activar una suscripción en período de prueba	`activate_subscription`	❌	❌
Previsualizar una actualización de una suscripción	`preview_subscription_update`	✅	❌
Crear un cargo único para una suscripción	`create_subscription_charge`	✅	❌
Previsualizar un cargo único para una suscripción	`preview_subscription_charge`	✅	❌

Métodos de pago guardados

Operación	Herramienta	No destructiva	Solo lectura
Listar métodos de pago guardados de un cliente	`list_saved_payment_methods`	✅	✅
Obtener un método de pago guardado de un cliente	`get_saved_payment_method`	✅	✅
Eliminar un método de pago guardado de un cliente	`delete_saved_payment_method`	❌	❌

Sesiones del portal de clientes

Operación	Herramienta	No destructiva	Solo lectura
Crear una sesión del portal de clientes	`create_customer_portal_session`	✅	❌

Configuración de notificaciones

Operación	Herramienta	No destructiva	Solo lectura
Listar configuraciones de notificaciones	`list_notification_settings`	✅	✅
Crear una configuración de notificaciones	`create_notification_setting`	✅	❌
Obtener una configuración de notificaciones	`get_notification_setting`	✅	✅
Actualizar una configuración de notificaciones	`update_notification_setting`	❌	❌
Eliminar una configuración de notificaciones	`delete_notification_setting`	❌	❌

Eventos

Operación	Herramienta	No destructiva	Solo lectura
Listar eventos	`list_events`	✅	✅

Notificaciones

Operación	Herramienta	No destructiva	Solo lectura
Listar notificaciones	`list_notifications`	✅	✅
Obtener una notificación	`get_notification`	✅	✅
Reenviar una notificación	`replay_notification`	✅	❌

Registros de notificaciones

Operación	Herramienta	No destructiva	Solo lectura
Listar registros de una notificación	`list_notification_logs`	✅	✅

Simulaciones

Operación	Herramienta	No destructiva	Solo lectura
Listar simulaciones	`list_simulations`	✅	✅
Crear una simulación	`create_simulation`	✅	❌
Obtener una simulación	`get_simulation`	✅	✅
Actualizar una simulación	`update_simulation`	❌	❌

Ejecuciones de simulación

Operación	Herramienta	No destructiva	Solo lectura
Listar ejecuciones de una simulación	`list_simulation_runs`	✅	✅
Crear una ejecución para una simulación	`create_simulation_run`	✅	❌
Obtener una ejecución de una simulación	`get_simulation_run`	✅	✅

Eventos de ejecución de simulación

Operación	Herramienta	No destructiva	Solo lectura
Listar eventos de una ejecución de simulación	`list_simulation_run_events`	✅	✅
Obtener un evento de una ejecución de simulación	`get_simulation_run_event`	✅	✅
Reenviar un evento de una ejecución de simulación	`replay_simulation_run_event`	✅	❌

Informes

Operación	Herramienta	No destructiva	Solo lectura
Listar informes	`list_reports`	✅	✅
Crear un informe	`create_report`	✅	❌
Obtener un informe	`get_report`	✅	✅
Obtener un archivo CSV de un informe	`get_report_csv`	✅	✅

Tokens del lado del cliente

Operación	Herramienta	No destructiva	Solo lectura
Listar tokens del lado del cliente	`list_client_side_tokens`	✅	✅
Crear un token del lado del cliente	`create_client_side_token`	✅	❌
Obtener un token del lado del cliente	`get_client_side_token`	✅	✅
Revocar un token del lado del cliente	`revoke_client_side_token`	❌	❌

Instalación

Para usar el servidor MCP, necesitarás una clave de API. Puedes crear y gestionar claves de API en Paddle > Developer tools > Authentication:

Sandbox: https://sandbox-vendors.paddle.com/authentication-v2
Live: https://vendors.paddle.com/authentication-v2

Agregar lo siguiente a tu archivo de configuración de MCP configurará y ejecutará el servidor MCP de Paddle en un cliente como Claude Desktop, Cursor o Windsurf:

Método 1: Instalación con un clic en Cursor o VS Code

Puedes instalar el servidor MCP de Paddle con un solo clic en Cursor o VS Code.

Después de la instalación, deberás actualizar la configuración en tu archivo de configuración de MCP para reemplazar your_api_key con tu clave de API real de Paddle y ajustar los valores de entorno y herramientas según sea necesario.

Método 2: Uso de argumentos de línea de comandos (Recomendado para `npx`)

Agrega lo siguiente al archivo de configuración o ajustes de MCP en el cliente que estés usando:

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

Reemplaza your_api_key con tu clave de API real de Paddle, establece --environment en sandbox o production, y establece --tools en las herramientas que deseas que se carguen y estén disponibles para el cliente MCP.

Método 3: Uso de variables de entorno

Agrega lo siguiente al archivo de configuración o ajustes de MCP en el cliente que estés 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"
      }
    }
  }
}

Reemplaza your_api_key con tu clave de API real de Paddle, establece PADDLE_ENVIRONMENT en sandbox o production, y establece PADDLE_MCP_TOOLS en las herramientas que deseas que se carguen y estén disponibles para el cliente MCP.

Filtrado de herramientas

Puedes filtrar qué herramientas se cargan y están disponibles para el cliente MCP pasando el argumento --tools (Método 2) o estableciendo la variable de entorno PADDLE_MCP_TOOLS (Método 1 o 3). Los valores aceptados son:

all - Todas las herramientas están disponibles
read-only - Solo las operaciones de lectura están disponibles
non-destructive - Las operaciones de lectura y las operaciones de escritura seguras están disponibles (predeterminado)
Una lista separada por comas de nombres de herramientas específicos (p. ej., list_products,get_product,create_product)

Para guías de configuración detalladas, consulta:

Desarrollo

Instala las dependencias:
```
pnpm install
```
Compila el servidor:
```
pnpm build
```
Actualiza el cliente para usar la compilación 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"
      }
    }
  }
}
```
La variable de entorno PADDLE_MCP_TOOLS acepta los mismos valores que el argumento --tools: all, read-only, non-destructive, o una lista de nombres de herramientas separados por comas. Si no se establece, el valor predeterminado es non-destructive.

Depuración

Para depurar el servidor MCP, puedes usar la herramienta MCP Inspector:

Ejecuta el servidor con el inspector:
```
pnpm inspector
```
Abre la URL proporcionada en tu navegador para ver y depurar las solicitudes y respuestas de MCP.
Incluye los argumentos --api-key y --environment.