PayPal MCP Server

The PayPal MCP Server implements the Model Context Protocol and gives AI agents direct access to core PayPal business functions, without anyone having to switch manually between a chat window and the PayPal dashboard. Per PayPal, the server is meant to lay the groundwork for a "more intelligent and responsive digital commerce ecosystem" and targets both developers building their own agentic workflows and merchants who want to connect their preferred AI tools directly to their own PayPal account. Technically, the server builds on the open-source PayPal Agent Toolkit, which supports MCP alongside OpenAI's Agent SDK, LangChain, and Vercel's AI SDK.

Tool catalog

The server covers seven functional areas: creating, listing, retrieving, sending, and reminding on invoices, plus cancelling, deleting, generating QR codes for, and setting up recurring series of them; creating and retrieving orders, and capturing payments and processing refunds; listing disputes, viewing their details, and accepting claims; creating, retrieving, and updating shipment tracking records; managing a product catalog (creating, listing, and viewing product details); managing subscription plans and subscriptions; and reporting tools for listing transactions and business insights.

Setup: local or as a hosted remote server

PayPal offers two access paths. Locally, the server can be started via npx -y @paypal/mcp --tools=all, with a PayPal access token and the environment (SANDBOX or PRODUCTION) passed as environment variables. Alternatively, PayPal operates a hosted remote server at mcp.sandbox.paypal.com (testing) and mcp.paypal.com (production), reachable via Server-Sent Events or Streamable HTTP through the mcp-remote helper tool. Remote access uses OAuth: you sign in with your own PayPal account and grant the client the requested permissions.

Keeping sandbox and production separate

For initial testing, PayPal explicitly recommends the sandbox environment with a PayPal developer account, since no real payments are processed there. Moving to production requires a regular PayPal business account and real credentials from the PayPal Developer Dashboard.

Security and write access

Because the server exposes both read and write tools, a misdirected or manipulated agent could trigger real business actions, such as sending invoices or issuing refunds. Before using it in production, check exactly which permissions the access token actually needs, and where possible require human confirmation for write actions in the MCP client being used.

Typical use cases

The server is particularly useful for small and mid-sized merchants who want to create invoices and payment reminders by voice or chat instead of through the dashboard, for example "Create a PayPal invoice for painting a house with a cost of $450, add 8% tax, and apply a 5% discount." It's equally suited to accounting and support tasks where an agent needs to look up payment status or disputes, and to automating recurring reporting on transactions and subscriptions.

Who the server is a good fit for

Developers building their own agent or checkout experiences with PayPal benefit from the local npm package and its source code. Merchants without their own development resources can instead use the hosted remote server directly with their existing PayPal account, without having to operate a server themselves.

For local use, Node.js version 18 or later plus a PayPal access token from the PayPal Developer Dashboard. For the hosted remote server, an MCP client with OAuth support and a PayPal account is enough; production payments require a regular PayPal business account instead of a sandbox developer account.

Locally in Claude Desktop or another client with an mcpServers configuration:

{
  "mcpServers": {
    "paypal": {
      "command": "npx",
      "args": ["-y", "@paypal/mcp", "--tools=all"],
      "env": {
        "PAYPAL_ACCESS_TOKEN": "YOUR_PAYPAL_ACCESS_TOKEN",
        "PAYPAL_ENVIRONMENT": "SANDBOX"
      }
    }
  }
}

Hosted remote server via Streamable HTTP (analogous via Server-Sent Events under /sse instead of /http):

{
  "mcpServers": {
    "paypal-mcp-server": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp.sandbox.paypal.com/http"]
    }
  }
}

On first use, the PayPal login page opens; after granting permission, the client needs to be restarted. Per the provider, clearing the local auth cache via rm -rf ~/.mcp-auth helps with connection issues.

npx -y @paypal/mcp --tools=all

Locally via a PayPal access token, passed as the PAYPAL_ACCESS_TOKEN environment variable or as a command-line argument. The hosted remote server instead uses OAuth: on first connection, you sign in with your own PayPal account and grant the client access.

Access scope depends on the access token used or the OAuth authorization of the signed-in PayPal account. --tools=all exposes every tool; individual tool groups (for example, only invoices) can also be restricted at startup.

Requests and tool parameters go to the PayPal API and are returned to the MCP client and its language model to answer the request. Responses can include payment, customer, invoice, and revenue data from the connected PayPal account. The local server runs as its own process on your own machine; the remote server runs on infrastructure operated by PayPal at mcp.paypal.com or mcp.sandbox.paypal.com.

Because the server exposes both read and write tools (sending invoices, issuing refunds, handling disputes), a misdirected or manipulated agent could trigger real business actions. Before production use, the access token should be restricted to the permissions actually needed, and, where supported by the client, human confirmation should be enabled for write actions. For initial testing, use the sandbox environment exclusively.