# mcp-paypal

MCP server connecting AI assistants to the PayPal REST API. Handles order checkout, recurring subscriptions, batch payouts, and customer dispute resolution.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 274
- Author: codespar
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/codespar/mcp-dev-latam/tree/HEAD/packages/payments/paypal
- Updated: 2026-09-27
- HTML: https://affpapa.org/en/nevibecode/mcp/mcp-paypal

## What it 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.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `PAYPAL_CLIENT_ID`, `PAYPAL_CLIENT_SECRET`, `PAYPAL_ENV` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
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-paypal
```
Replace <…> with your own values

### Codex

**Platform CLI**
```bash
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-paypal
```
Replace <…> with your own values

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "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

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "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

### Gemini CLI

**Platform CLI**
```bash
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-paypal
```
Replace <…> with your own values

## When to use it
- 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
- 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

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [CCXT](https://affpapa.org/en/nevibecode/mcp/ccxt.md) — MCP server · ★ 44583
- [Finance Toolkit](https://affpapa.org/en/nevibecode/mcp/finance-toolkit.md) — MCP server · ★ 5458
- [EdgarTools](https://affpapa.org/en/nevibecode/mcp/edgartools.md) — MCP server · ★ 2814
- [LetsFG — Flights & Hotels](https://affpapa.org/en/nevibecode/mcp/letsfg-flights-hotels.md) — MCP server · ★ 2188
- [AutoTS](https://affpapa.org/en/nevibecode/mcp/autots.md) — MCP server · ★ 1434

From the same set: [codespar/mcp-dev-latam](https://affpapa.org/en/nevibecode/by/codespar/mcp-dev-latam.md) — 124 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md