@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