Skip to content
Back to search

paypalmcp

Read-only MCP server over stdio for questions about PayPal transactions, balances and subscriptions, held to a daily request budget per account.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hampel--paypalmcp/badge.svg)](/listings/hampel--paypalmcp)

HTML

<a href="/listings/hampel--paypalmcp"><img src="/api/listings/hampel--paypalmcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Download `paypalmcp-<version>` and `SHA256SUMS` from the release, verify, and install the binary:

sha256sum --ignore-missing -c SHA256SUMS
install -m 0755 paypalmcp-<version> /usr/local/bin/paypalmcp

From a checkout, `composer install` and run `php paypalmcp` in place of `paypalmcp`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 167 lines
  1. # paypalmcp — PayPal lookups over MCP
  2. A read-only [MCP](https://modelcontextprotocol.io/) server, over stdio, that lets an agent answer
  3. questions about one or more PayPal business accounts: what a person paid and when, a transaction
  4. by its id, fees and totals over a period, balances, and a subscription's state. It is for an
  5. operator's agent that needs those answers without holding a PayPal login itself.
  6. **Nothing it does can move money or change an account, and every request it sends is counted.**
  7. Both are the point of it; see *Safety*.
  8. ## Requirements
  9. PHP 8.3 or later. A PayPal REST app for each account, made for this server alone, with
  10. Transaction Search and Subscriptions ticked.
  11. ## Installation
  12. Download `paypalmcp-<version>` and `SHA256SUMS` from the release, verify, and install the binary:
  13. ```bash
  14. sha256sum --ignore-missing -c SHA256SUMS
  15. install -m 0755 paypalmcp-<version> /usr/local/bin/paypalmcp
  16. ```
  17. From a checkout, `composer install` and run `php paypalmcp` in place of `paypalmcp`.
  18. ## Configuration
  19. Three things: an environment file, an account inventory, and a state directory.
  20. **The environment file** says where the state lives, and holds no credential. `.env.example` is
  21. the template and says where the file is looked for. A variable already set, exported or passed
  22. by the MCP client, wins over the same key in the file.
  23. ```dotenv
  24. PAYPALMCP_STATE_PATH=/var/lib/paypalmcp
  25. APP_TIMEZONE=Australia/Sydney
  26. ```
  27. `APP_TIMEZONE` is the zone a bare date such as `2026-03-01` is read in, as the whole of that day.
  28. Times PayPal reports keep their own offset.
  29. **The account inventory** names the accounts and holds the REST app for each.
  30. `accounts.toml.example` is the template; by default it is `accounts.toml` in the state directory.
  31. It holds client secrets, so `app:validate` fails it at anything wider than 0600, or root-owned
  32. and 0640 for a group.
  33. ```toml
  34. [acme]
  35. name = "Acme Example Pty Ltd"
  36. environment = "live"
  37. client_id = "..."
  38. secret = "..."
  39. # daily_budget = 500
  40. ```
  41. The table name is the key every tool takes. `environment` is required: `live` or `sandbox`.
  42. **The state directory** is created 0700 on first use. It holds cached PayPal tokens, each
  43. account's request count, and the months of transactions already read, payers' names and emails
  44. among them. Set it absolutely: a compiled binary otherwise uses the working directory, which the
  45. MCP client chooses.
  46. ```bash
  47. paypalmcp app:config # what is configured, and the .env actually read
  48. paypalmcp app:validate # checks it, and asks PayPal for what the tools need
  49. ```
  50. `app:validate` sends four requests to each account, counted against its budget. `--offline`
  51. skips them; `--strict` exits 2 on a warning.
  52. | | all fine | warnings only | any failure |
  53. |---|---|---|---|
  54. | `app:validate` | 0 | 0 | 1 |
  55. | `app:validate --strict` | 0 | 2 | 1 |
  56. 1 means failed, with the flag or without it: not the monitoring-plugin numbering, where 1 is a
  57. warning.
  58. ## REST apps
  59. **Give each account its own app, made for this server alone**, from the Apps & Credentials page
  60. of PayPal's developer dashboard, so it can be revoked without touching anything else and its
  61. token cache is its own.
  62. **Tick Transaction Search and Subscriptions on it, and nothing else.** Every transaction and
  63. balance tool needs Transaction Search; `get-subscription` needs Subscriptions, which Transaction
  64. Search does not grant. `account-access` and `app:validate` read from the token whether each is
  65. there.
  66. **A change to an existing app's features waits for its token to expire**, up to nine hours:
  67. PayPal hands back the same token until then, so forgetting the cached one does not help. A new
  68. app's first token has its features at once.
  69. **An app's token can do more than its ticked features say.** With only those two ticked, a sandbox
  70. app's token still carried refund and payment scopes (2026-11-21): PayPal has no read-only app. What keeps this server read-only is that it has no code that writes; see *Safety*.
  71. ## Registering the server
  72. With Claude Code:
  73. ```bash
  74. claude mcp add paypal -- paypalmcp mcp:start paypal
  75. ```
  76. Any MCP client that starts a stdio server works the same way: the command is
  77. `paypalmcp mcp:start paypal`. If the environment file is not in one of the places looked for, set
  78. `PAYPALMCP_ENV` in the environment the client starts it with.
  79. ## Tools
  80. | tool | answers | costs |
  81. |---|---|---|
  82. | `list-accounts` | the configured accounts and their budgets | nothing |
  83. | `account-access` | whether the app is accepted, and has the features the tools need | a token, or nothing |
  84. | `search-transactions` | rows in a range, by event code, currency or status | about 1 a month |
  85. | `find-payer` | rows whose payer matches an email, account id or name | about 1 a month |
  86. | `transaction-totals` | count, gross, fees and net by currency and event code | about 1 a month |
  87. | `get-transaction` | one transaction, with its conversion rows | 1 or 2 with a date, 1 a month without |
  88. | `balances` | each currency's balance, as of PayPal's last refresh | 1 |
  89. | `get-subscription` | a subscription's state and its recent payments | 2 |
  90. A call costs one more when no token is cached. Every answer carries `budget`: what the call sent
  91. and what is left.
  92. ### Coverage
  93. **PayPal's reporting lags, and it cuts a search back to its last refresh without saying so.** A
  94. payment takes up to three hours to appear. So every answer built from transaction history carries
  95. `coverage`: the range asked for, the range actually read, and a sentence saying why they differ.
  96. ### Months
  97. **PayPal searches at most 31 days at a time, keeps three years, and cannot search by person.** So
  98. the server reads history one UTC calendar month at a time, newest first, and filters here. A month
  99. that ended more than three days ago is kept for 30 days, so asking about it again costs nothing.
  100. `max_requests` caps a call; when it runs out the answer says how far back it reached.
  101. ### Payers
  102. **A row goes out with the payer's name, PayPal login email, PayPal account id and country.** Their
  103. phone number and every postal address are withheld, from answers and from the cache. The email is
  104. the payer's PayPal login, which is often not the address they gave the seller; `custom_field` is
  105. the seller's own reference where one was set.
  106. ## Safety
  107. **Read-only in the code, because the credential is not.** paypal-api wraps no operation that moves
  108. money or changes an account, and this server calls nothing else and has no tool that sends a raw
  109. request.
  110. **Each account has a budget over any 24 hours**, 500 requests unless set otherwise, kept in the
  111. state directory and shared by every server process. PayPal publishes no rate limit; the budget
  112. bounds what one conversation can send. A call sets aside the most it might send before it starts;
  113. one that does not fit is refused without asking PayPal. Every request crosses one transport that
  114. counts it, and a request from anywhere else is refused.
  115. ## Development
  116. ```bash
  117. composer check # phpstan, then pest
  118. composer build # the release phar, into builds/
  119. ```
  120. ## Licence
  121. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.