mcp-paypal — Claude Code MCP server: what it does, how to install
MCP server connecting AI assistants to the PayPal REST API. Handles order checkout, recurring subscriptions, batch payouts, and customer dispute resolution.
claude mcp add --env PAYPAL_CLIENT_ID=<PAYPAL_CLIENT_ID> --env PAYPAL_CLIENT_SECRET=<PAYPAL_CLIENT_SECRET> --env PAYPAL_ENV=<PAYPAL_ENV> --transport stdio paypal -- npx -y @codespar/mcp-paypalWhat mcp-paypal does
This server exposes 19 tools for interacting with PayPal services. It allows agents to generate orders, authorize and capture charges, issue refunds, or release authorizations. Beyond direct checkout, it handles batch payouts, manages recurring billing subscriptions, and inspects incoming webhook event signatures. When dealing with conflicts, agents can retrieve dispute details or accept buyer claims.
The package runs over stdio or as an HTTP service on port 3000. It authenticates via OAuth2 client_credentials, posting credentials to the token endpoint and caching access tokens until 60 seconds before expiration. For captures and refunds, the server passes the PayPal-Request-Id header to ensure idempotency across retries.
Without valid credentials in PAYPAL_CLIENT_ID and PAYPAL_CLIENT_SECRET, requests fail immediately. Pay attention to transaction amounts: PayPal expects an object with a currency code and a decimal string value.
What it helps with
- create and capture PayPal orders using checkout endpoints
- distribute batch payouts to external recipients
- set up, inspect, and cancel recurring billing subscriptions
- track customer disputes and accept liability on open claims
- validate signatures on received webhook notifications
Example prompts for the agent
- Create a PayPal order for 24.00 USD for item SKU-104
- Fetch the status of the payout batch with ID batch-8812
- List recent customer disputes and inspect the claim details for dispute-550
How to install mcp-paypal
Platform CLI
claude mcp add --env PAYPAL_CLIENT_ID=<PAYPAL_CLIENT_ID> --env PAYPAL_CLIENT_SECRET=<PAYPAL_CLIENT_SECRET> --env PAYPAL_ENV=<PAYPAL_ENV> --transport stdio paypal -- npx -y @codespar/mcp-paypalReplace <…> with your own values
Platform CLI
codex mcp add paypal --env PAYPAL_CLIENT_ID=<PAYPAL_CLIENT_ID> --env PAYPAL_CLIENT_SECRET=<PAYPAL_CLIENT_SECRET> --env PAYPAL_ENV=<PAYPAL_ENV> -- npx -y @codespar/mcp-paypalReplace <…> with your own values
Config file
{
"mcpServers": {
"paypal": {
"command": "npx",
"args": [
"-y",
"@codespar/mcp-paypal"
],
"env": {
"PAYPAL_CLIENT_ID": "<PAYPAL_CLIENT_ID>",
"PAYPAL_CLIENT_SECRET": "<PAYPAL_CLIENT_SECRET>",
"PAYPAL_ENV": "<PAYPAL_ENV>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"paypal": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@codespar/mcp-paypal"
],
"env": {
"PAYPAL_CLIENT_ID": "<PAYPAL_CLIENT_ID>",
"PAYPAL_CLIENT_SECRET": "<PAYPAL_CLIENT_SECRET>",
"PAYPAL_ENV": "<PAYPAL_ENV>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e PAYPAL_CLIENT_ID=<PAYPAL_CLIENT_ID> -e PAYPAL_CLIENT_SECRET=<PAYPAL_CLIENT_SECRET> -e PAYPAL_ENV=<PAYPAL_ENV> paypal npx -y @codespar/mcp-paypalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about mcp-paypal
How do I install mcp-paypal in Claude Code?
Run claude mcp add mcp-paypal -e PAYPAL_CLIENT_ID=<PAYPAL_CLIENT_ID> -e PAYPAL_CLIENT_SECRET=<PAYPAL_CLIENT_SECRET> -- npx -y @codespar/mcp-paypal. Replace placeholders with your PayPal REST credentials.
What does mcp-paypal do?
It equips your AI model with 19 tools to run payment checkouts, initiate payouts, handle subscription billing, and process buyer dispute claims.
How does environment switching work?
Set PAYPAL_ENV="live" to route traffic to the production endpoint. By default, the server runs in sandbox mode against api-m.sandbox.paypal.com.
