@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

Related MCP server: PayPal MCP Server

Configure

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):

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

License

MIT