About mcp-paypal
mcp-paypal is an MCP server for PayPal that wraps the PayPal REST API for global payments and payouts, with 19 tools covering orders, subscriptions and disputes. It targets LatAm SaaS and marketplaces that already hold a PayPal merchant account and want agent-driven checkout and payouts. It supports both sandbox and live environments.
Key features
- 01Provides 19 PayPal-related tools
- 02Supports order creation, authorization, capture and refunds
- 03Supports batch payouts and payout item lookup
- 04Manages subscription creation, lookup and cancellation
- 05Covers dispute lookup and webhook signature verification
Use cases
- 01Creating and capturing PayPal orders through an agent
- 02Running batch payouts and checking payout status
- 03Managing subscriptions and handling dispute claims
MCP support
This project is an MCP server that exposes PayPal REST API operations as tools to MCP clients.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
npx -y @codespar/mcp-paypalPAYPAL_CLIENT_IDPayPal REST app client id (from developer.paypal.com Apps & Credentials).PAYPAL_CLIENT_SECRETSecretPayPal REST app client secret (OAuth2 client_credentials password).PAYPAL_ENVPayPal environment. 'sandbox' (default, https://api-m.sandbox.paypal.com) or 'live' (https://api-m.paypal.com).Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.
Tools
19Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| body | object | No | Additional Order create body fields merged into the request (application_context, etc). |
| intent | enum | Yes | Capture immediately on buyer approval, or authorize for later capture.CAPTURE | AUTHORIZE |
| payment_source | object | No | Optional payment_source object (e.g. { paypal: { experience_context: { return_url, cancel_url } } } or { card: { ... } }). |
| purchase_units | array | Yes | Array of purchase_unit objects. Each must include amount: { currency_code, value }. Optional: reference_id, description, items, shipping, payee. |
| paypalRequestId | string | No | Optional PayPal-Request-Id header for idempotency. |
Details
From the project README@codespar/mcp-paypal
MCP server for PayPal — global payments and payouts via the PayPal REST API.
Target customer: LatAm SaaS / marketplaces selling globally that already hold a PayPal merchant account and want agent-driven checkout, payouts, subscriptions, and dispute handling.
Tools (19)
| Tool | Purpose |
|---|---|
create_order | Create a PayPal Order via POST /v2/checkout/orders. |
get_order | Fetch a PayPal Order by id via GET /v2/checkout/orders/{id}. |
capture_order | Capture payment for an approved order via POST /v2/checkout/orders/{id}/capture. |
authorize_order | Authorize payment for an approved order via POST /v2/checkout/orders/{id}/authorize. |
capture_authorization | Capture a previously authorized payment via POST /v2/payments/authorizations/{id}/capture. |
refund_capture | Refund a captured payment via POST /v2/payments/captures/{id}/refund. |
void_authorization | Void (release) an unsettled authorization via POST /v2/payments/authorizations/{id}/void. |
get_payment_details | Fetch a payment object by id via GET /v2/payments/{type}/{id}. |
create_batch_payout | Create a batch payout via POST /v1/payments/payouts. |
get_payout | Fetch a payout batch by id via GET /v1/payments/payouts/{batch_id}. |
get_payout_item | Fetch a single payout item by id via GET /v1/payments/payouts-item/{item_id}. |
create_subscription | Create a billing subscription via POST /v1/billing/subscriptions. |
get_subscription | Fetch a subscription by id via GET /v1/billing/subscriptions/{id}. |
cancel_subscription | Cancel an active subscription via POST /v1/billing/subscriptions/{id}/cancel. |
list_disputes | List disputes via GET /v1/customer/disputes. |
get_dispute | Fetch a dispute by id via GET /v1/customer/disputes/{id}. |
accept_dispute_claim | Accept liability for a dispute claim via POST /v1/customer/disputes/{id}/accept-claim. |
list_webhooks | List configured webhooks for the app via GET /v1/notifications/webhooks. |
verify_webhook_signature | Verify a webhook event signature via POST /v1/notifications/verify-webhook-signature. |
Install
npm install @codespar/mcp-paypal
Environment
PAYPAL_CLIENT_ID="..." # REST app client id
PAYPAL_CLIENT_SECRET="..." # REST app client secret (OAuth2)
PAYPAL_ENV="sandbox" # 'sandbox' (default) or 'live'
Endpoints:
sandbox->https://api-m.sandbox.paypal.comlive->https://api-m.paypal.com
Authentication
PayPal REST APIs use OAuth2 client_credentials. The server posts CLIENT_ID:CLIENT_SECRET (Basic auth) to /v1/oauth2/token with grant_type=client_credentials and caches the bearer token until 60s before expiry, refreshing on demand.
Run
# stdio (default — for Claude Desktop, Cursor, etc)
npx @codespar/mcp-paypal
# HTTP (for server-to-server testing)
MCP_HTTP=true MCP_PORT=3000 npx @codespar/mcp-paypal
Notes
- Amounts are objects in PayPal REST:
{ "currency_code": "USD", "value": "10.50" }. Values are decimal strings. - The server forwards arbitrary REST body fields verbatim under
bodyfor tools that accept them, so any field documented in the PayPal REST reference can be passed even if it's not in the MCPinputSchema. - For payment captures / refunds the
PayPal-Request-Idheader (idempotency) is forwarded when supplied.
Enterprise
Need governance, budget limits, and audit trails for agent payments? CodeSpar Enterprise adds policy engine, payment routing, and compliance templates on top of these MCP servers.
License
MIT
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.