@imazhar101/paypal-mcp

A lite Model Context Protocol server for PayPal.

Unlike PayPal's official @paypal/mcp (which pulls in the entire LangChain / Vercel-AI agent-toolkit and expects a pre-minted, short-lived access token), this server is intentionally small:

• No heavy dependencies — just @modelcontextprotocol/sdk + zod. Calls the PayPal REST API directly with fetch.
• Owns its token lifecycle — you give it a durable client id + secret; it mints, caches, and refreshes the client_credentials access token itself. Proactive refresh (expiry skew) + reactive refresh (re-mint + retry once on a 401). A long-lived host (e.g. an MCP gateway) can spawn one child per merchant with only the static client-id/secret in its env and never babysit token expiry.
• Read-only by default — this server handles money. Write/refund/payout tools are not registered unless you opt in with PAYPAL_READONLY=0.

Install

npm install -g @imazhar101/paypal-mcp

Configure

| Env var | Required | Default | Notes | | ---------------------- | -------- | --------- | ---------------------------------------- | | PAYPAL_CLIENT_ID | yes | — | PayPal REST app client id | | PAYPAL_CLIENT_SECRET | yes | — | PayPal REST app secret | | PAYPAL_ENVIRONMENT | no | SANDBOX | SANDBOX or PRODUCTION | | PAYPAL_READONLY | no | 1 | 1/true = read tools only; 0 = also write tools |

Create a REST app and obtain credentials at the PayPal Developer Dashboard. The app must have the relevant features enabled (Invoicing, Transaction Search, etc.) or those tools will return 403 NOT_AUTHORIZED.

Run (stdio)

PAYPAL_CLIENT_ID=... PAYPAL_CLIENT_SECRET=... PAYPAL_ENVIRONMENT=SANDBOX paypal-mcp

Claude Code / MCP client config

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@imazhar101/paypal-mcp"],
      "env": {
        "PAYPAL_CLIENT_ID": "...",
        "PAYPAL_CLIENT_SECRET": "...",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

Tools

Read-only (always registered):

| Tool | PayPal API | | -------------------------- | ----------------------------------------- | | paypal_verify_connection | mints a token; reports environment | | paypal_list_transactions | GET /v1/reporting/transactions | | paypal_get_balances | GET /v1/reporting/balances | | paypal_list_invoices | GET /v2/invoicing/invoices | | paypal_get_invoice | GET /v2/invoicing/invoices/{id} | | paypal_get_order | GET /v2/checkout/orders/{id} | | paypal_get_capture | GET /v2/payments/captures/{id} | | paypal_list_disputes | GET /v1/customer/disputes | | paypal_get_dispute | GET /v1/customer/disputes/{id} | | paypal_list_plans | GET /v1/billing/plans | | paypal_get_subscription | GET /v1/billing/subscriptions/{id} |

Write tools (create/send invoice, refund, …) are a deliberate follow-up gated behind PAYPAL_READONLY=0.

License

MIT