PayPal MCP Server

oficial

El servidor del Protocolo de Contexto de Modelo de PayPal permite la integración con las APIs de PayPal mediante llamadas a funciones. Este protocolo admite diversas herramientas para interactuar con diferentes servicios de PayPal.

GitHub
187

Documentación

PayPal Agent Toolkit

El PayPal Agent Toolkit permite que los frameworks de agentes más populares, como el SDK de Agentes de OpenAI, LangChain, el SDK de IA de Vercel y el Protocolo de Contexto de Modelo (MCP), se integren con las APIs de PayPal mediante la invocación de funciones. Incluye soporte para TypeScript y está construido sobre las APIs de PayPal y los SDKs de PayPal.

Herramientas disponibles

El PayPal Agent Toolkit proporciona las siguientes herramientas:

Facturas

  • create_invoice: Crear una nueva factura en el sistema de PayPal
  • list_invoices: Listar facturas con paginación y filtrado opcionales
  • get_invoice: Recuperar los detalles de una factura específica
  • send_invoice: Enviar una factura a los destinatarios
  • send_invoice_reminder: Enviar un recordatorio para una factura existente
  • cancel_sent_invoice: Cancelar una factura enviada
  • generate_invoice_qr_code: Generar un código QR para una factura

Pagos

  • create_order: Crear una orden en el sistema de PayPal basada en los detalles proporcionados
  • get_order: Recuperar los detalles de una orden
  • pay_order: Procesar el pago de una orden autorizada
  • create_refund: Procesar un reembolso para un pago capturado.
  • get_refund: Obtener los detalles de un reembolso específico.

Gestión de Disputas

  • list_disputes: Recuperar un resumen de todas las disputas abiertas
  • get_dispute: Recuperar información detallada de una disputa específica
  • accept_dispute_claim: Aceptar una reclamación de disputa

Seguimiento de Envíos

  • create_shipment_tracking: Crear un registro de seguimiento de envío
  • get_shipment_tracking: Recuperar información de seguimiento de envío
  • update_shipment_tracking: Actualizar información de seguimiento de envío

Gestión de Catálogo

  • create_product: Crear un nuevo producto en el catálogo de PayPal
  • list_products: Listar productos con paginación y filtrado opcionales
  • show_product_details: Recuperar los detalles de un producto específico

Gestión de Suscripciones

  • create_subscription_plan: Crear un nuevo plan de suscripción
  • list_subscription_plans: Listar planes de suscripción
  • show_subscription_plan_details: Recuperar los detalles de un plan de suscripción específico
  • create_subscription: Crear una nueva suscripción
  • show_subscription_details: Recuperar los detalles de una suscripción específica
  • update_subscription: Actualizar una suscripción existente
  • cancel_subscription: Cancelar una suscripción activa

Informes y Analíticas

  • list_transactions: Listar transacciones con paginación y filtrado opcionales
  • get_merchant_insights: Recuperar métricas de inteligencia de negocio y analíticas para un comerciante

TypeScript

Instalación

No necesitas este código fuente a menos que quieras modificar el paquete. Si solo quieres usar el paquete, ejecuta:

npm install @paypal/agent-toolkit

Requisitos

  • Node 18+

Uso

La biblioteca necesita ser configurada con el ID de cliente y el secreto de tu cuenta, disponibles en tu Panel de Desarrollador de PayPal.

El toolkit funciona con el SDK de IA de Vercel y puede pasarse como una lista de herramientas. Para más detalles, consulta nuestros ejemplos.

import { PayPalAgentToolkit } from '@paypal/agent-toolkit/ai-sdk';
const paypalToolkit = new PayPalAgentToolkit({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: {
      invoices: {
        create: true,
        list: true,
        send: true,
        sendReminder: true,
        cancel: true,
        generateQRC: true,
      },
      products: { create: true, list: true, update: true },
      subscriptionPlans: { create: true, list: true, show: true },
      shipment: { create: true, show: true, cancel: true },
      orders: { create: true, get: true },
      disputes: { list: true, get: true },
    },
  },
});

Para usar el modo sandbox, añade contexto dentro de tu configuración.

configuration: {
  context: {
    sandbox: true,
  }
}

Inicializando los Flujos de Trabajo

import { PayPalWorkflows, ALL_TOOLS_ENABLED } from '@paypal/agent-toolkit/ai-sdk';
const paypalWorkflows = new PayPalWorkflows({
  clientId: process.env.PAYPAL_CLIENT_ID,
  clientSecret: process.env.PAYPAL_CLIENT_SECRET,
  configuration: {
    actions: ALL_TOOLS_ENABLED,
  },
});

Uso

Usando el toolkit

const llm: LanguageModelV1 = getModel(); // The model to be used with ai-sdk
const { text: response } = await generateText({
  model: llm,
  tools: paypalToolkit.getTools(),
  maxSteps: 10,
  prompt: `Create an order for $50 for custom handcrafted item and get the payment link.`,
});

Variables de Entorno

Se pueden usar las siguientes variables de entorno:

  • PAYPAL_ACCESS_TOKEN: Tu Token de Acceso de PayPal
  • PAYPAL_ENVIRONMENT: Establecer a SANDBOX para modo sandbox, PRODUCTION para producción (por defecto es modo SANDBOX)

Esta guía explica cómo generar un token de acceso para la integración con la API de PayPal, incluyendo cómo encontrar tu ID de cliente y secreto de cliente.

Prerrequisitos

  • Cuenta de Desarrollador de PayPal (para Sandbox)
  • Cuenta de Negocios de PayPal (para producción)

Encontrando tu ID de Cliente y Secreto de Cliente

  1. Crear una Cuenta de Desarrollador de PayPal:

  2. Acceder a tus Credenciales:

    • En el Panel de Desarrollador, haz clic en Apps y Credenciales en el menú
    • Cambia entre los modos Sandbox y Live según tus necesidades

  3. Crear o Ver una App:

    • Para crear una nueva app, haz clic en Crear App
    • Dale un nombre a tu app y selecciona una cuenta de Negocios para asociarla
    • Para apps existentes, haz clic en el nombre de la app para ver los detalles

  4. Recuperar Credenciales:

    • Una vez que tu app esté creada o seleccionada, verás una pantalla con:
      • ID de Cliente: Un identificador público para tu app
      • Secreto de Cliente: Una clave privada (se muestra después de hacer clic en "Mostrar")
    • Guarda estas credenciales de forma segura, ya que son necesarias para generar tokens de acceso

Generando un Token de Acceso

Usando cURL

curl -v https://api-m.sandbox.paypal.com/v1/oauth2/token \\
  -H \"Accept: application/json\" \\
  -H \"Accept-Language: en_US\" \\
  -u \"CLIENT_ID:CLIENT_SECRET\" \\
  -d \"grant_type=client_credentials\"

Reemplaza CLIENT_ID y CLIENT_SECRET con tus credenciales reales. Para producción, usa https://api-m.paypal.com en lugar de la URL de sandbox.

Usando Postman

  1. Crea una nueva solicitud a https://api-m.sandbox.paypal.com/v1/oauth2/token
  2. Establece el método en POST
  3. En Autorización, selecciona Autenticación Básica e ingresa tu ID de Cliente y Secreto de Cliente
  4. En Cuerpo, selecciona x-www-form-urlencoded y añade una clave grant_type con el valor client_credentials
  5. Envía la solicitud

Respuesta

Una respuesta exitosa se verá así:

{
  "scope": "...",
  "access_token": "Your Access Token",
  "token_type": "Bearer",
  "app_id": "APP-80W284485P519543T",
  "expires_in": 32400,
  "nonce": "..."
}

Copia el valor de access_token para usarlo en tu integración con Claude Desktop.

Detalles del Token

  • Tokens de Sandbox: Válidos por 3-8 horas
  • Tokens de Producción: Válidos por 8 horas
  • Se recomienda implementar lógica de refresco de token antes de la expiración

Usando el Token con Claude Desktop

Una vez que tengas tu token de acceso, actualiza el valor de PAYPAL_ACCESS_TOKEN en la configuración de tu conector de Claude Desktop:

{
  "env": {
    "PAYPAL_ACCESS_TOKEN": "YOUR_NEW_ACCESS_TOKEN",
    "PAYPAL_ENVIRONMENT": "SANDBOX"
  }
}

Mejores Prácticas

  1. Almacena el ID de cliente y el secreto de cliente de forma segura
  2. Implementa lógica de refresco de token para manejar la expiración del token
  3. Usa tokens específicos del entorno (sandbox para pruebas, producción para transacciones reales)
  4. Evita incrustar tokens directamente en el código de la aplicación

Aviso Legal

El contenido generado por IA puede ser inexacto o estar incompleto. Los usuarios son responsables de verificar de forma independiente cualquier información antes de confiar en ella. PayPal no ofrece garantías sobre la precisión de los resultados y no se hace responsable de ninguna decisión, acción o consecuencia derivada de su uso.