PayPal MCP Server

Official PayPal MCP server for managing invoices, orders, subscriptions, shipments, products, and disputes through PayPal APIs via natural language.

Payments by PayPal Bearer Token active

Connect (Remote Server) GitHub Docs npm: @paypal/mcp

Overview

The PayPal MCP server is an official integration from PayPal that exposes PayPal's commerce APIs to MCP-compatible AI clients like Claude Desktop, Cursor, and Cline. It is part of the broader @paypal/agent-toolkit open-source project, which also supports OpenAI's Agents SDK, LangChain, and Vercel's AI SDK. The MCP server lets merchants and developers run business workflows such as invoicing, order capture, dispute handling, and subscription management through natural language conversations.

The server covers a wide surface area of the PayPal platform: invoicing (create, send, remind, QR codes), orders (create, get, capture), subscription plans and subscriptions, product catalog, shipment tracking, dispute management, and transaction reporting. It can run locally via npx @paypal/mcp against the PayPal sandbox or production environment, or you can connect to PayPal's remote-hosted endpoints at https://mcp.sandbox.paypal.com and https://mcp.paypal.com via SSE or streamable HTTP.

Authentication uses a PayPal access token generated from a Client ID and Client Secret in the PayPal Developer Dashboard. Sandbox tokens are valid for 3 to 8 hours, so longer-running setups typically use the remote server with OAuth-style client credentials.

Tools

Tool	Description
`create_invoice`	Create a new draft invoice in PayPal Invoicing.
`list_invoices`	List invoices with optional pagination and filtering.
`get_invoice`	Retrieve full details of a specific invoice by ID.
`send_invoice`	Send an existing invoice to its recipients.
`send_invoice_reminder`	Send a reminder email for an existing unpaid invoice.
`cancel_sent_invoice`	Cancel an invoice that has already been sent.
`generate_invoice_qr_code`	Generate a QR code image for a given invoice for in-person payment.
`create_order`	Create a PayPal order to start a checkout flow.
`get_order`	Get the status and details of an order.
`capture_order`	Capture payment for an authorized order.
`create_product`	Create a product in the PayPal catalog.
`list_products`	List products in the catalog.
`show_product_details`	Get details for a specific catalog product.
`update_product`	Update fields on an existing catalog product.
`create_subscription_plan`	Create a billing plan for subscriptions.
`list_subscription_plans`	List existing subscription plans.
`show_subscription_plan_details`	Get details of a subscription plan.
`create_subscription`	Create a new subscription for a customer against a plan.
`show_subscription_details`	Get the current status and details of a subscription.
`cancel_subscription`	Cancel an active subscription.
`create_shipment`	Create a shipment tracking record tied to a PayPal transaction.
`get_shipment_tracking`	Retrieve tracking info for a shipment.
`list_disputes`	List disputes filed against the merchant.
`get_dispute`	Get details on a specific dispute case.
`accept_dispute_claim`	Accept a dispute claim and issue a refund.
`list_transactions`	List transactions for the merchant with filtering.

Setup Guide

Prerequisites

Node.js v18 or later (for local install)
PayPal Developer account with Client ID and Client Secret from the PayPal Developer Dashboard
A generated PayPal access token (sandbox or production)

Option 1: Local install via npx

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@paypal/mcp", "--tools=all"],
      "env": {
        "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

Set PAYPAL_ENVIRONMENT to PRODUCTION for live mode. You can also pass the token via --access-token instead of the env var, or scope tools with --tools=invoices,orders instead of all.

Option 2: Remote hosted server

PayPal hosts the MCP server at https://mcp.sandbox.paypal.com (sandbox) and https://mcp.paypal.com (production). Connect via SSE using mcp-remote:

{
  "mcpServers": {
    "paypal-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.sandbox.paypal.com/sse"]
    }
  }
}

A /http endpoint is also available for streamable HTTP transport. Authentication on the remote server uses PayPal Client ID and Secret.

Troubleshooting

If you hit auth errors, clear cached MCP credentials with rm -rf ~/.mcp-auth.

Use Cases

Generate and send PayPal invoices from natural language descriptions, including QR codes for in-person collection
Reconcile orders by listing transactions in a date range, fetching disputes, and capturing authorized but uncaptured orders
Manage a SaaS subscription catalog: create products, define billing plans, and provision or cancel subscriptions on customer request
Triage disputes by listing open cases, fetching details, and accepting low-value claims automatically based on rules
Automate shipping confirmation by creating shipment tracking records against captured PayPal orders

Example Prompts

"Create a draft invoice in PayPal for Acme Corp for 3 hours of consulting at $200/hour in USD and send it."
"List all invoices that are still unpaid after 30 days and send reminders to each recipient."
"Show me PayPal transactions from last week, total them by currency, and flag any disputes."
"Create a $29/month subscription plan called Pro Tier under our existing SaaS product, then subscribe customer alice@example.com to it."
"Capture order ID 5O190127TN364715T and create a shipment tracking record with carrier UPS and tracking 1Z999AA10123456784."

Pros

Official, first-party implementation maintained by PayPal under the paypal GitHub org
Broad API coverage across invoicing, orders, subscriptions, catalog, shipments, disputes, and transactions
Both local (npx @paypal/mcp) and remote-hosted (mcp.paypal.com) options with sandbox and production environments
Part of a multi-framework toolkit, so tool definitions stay consistent with PayPal's LangChain, OpenAI Agents SDK, and Vercel AI SDK integrations

Limitations

Local mode uses a short-lived access token (3 to 8 hours in sandbox), which requires periodic refresh from the Developer Dashboard
Some advanced payout and payments APIs (mass payouts, vault, payment methods tokens) are not exposed as MCP tools
Tool documentation is split between the GitHub README and PayPal's docs site, making discovery uneven

Alternatives

Stripe Agent Toolkit MCP for Stripe payments, subscriptions, and invoicing
Square MCP server for Square commerce APIs as an alternative payments stack
Building a custom MCP server directly against the PayPal REST APIs if you need endpoints not covered by the official toolkit