PayPal Operations Agent
Provides sandbox tools for reading PayPal disputes and unpaid invoices, creating persistent payment reminder proposals, and executing approved invoice reminders through PayPal OAuth. Includes a webhook receiver that verifies PayPal signatures and durably deduplicates deliveries.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
PayPal Operations Agent
Judges: try the project without credentials
A PayPal sandbox prototype for the administrative lead at a small agency who reviews overdue invoices and decides which customer to follow up with first. It explains an invoice’s position using its deadline, outstanding amount, previous reminders and open dispute status, compares that order with deadline-only sorting, and prepares a reminder draft for the AI client to rewrite before separate human approval and controlled execution. The hypothesis is that this workflow could make follow-up decisions easier; no real-user adoption, time savings or improvement in collections has been measured.
Install, build, and test
Requires Node.js 22.23.3 or later and npm. Run all commands from the project root:
npm ci
npm run build
npm testBuild before testing: the console API test imports compiled files. The test suite targets Linux and macOS (CI runs on Ubuntu); the approval CLI tests need python3 to open a pseudo-terminal. Node's TypeScript stripping and built-in SQLite may emit experimental warnings.
Related MCP server: week7-mcp-server
Open the local demo console
No PayPal credentials are required. After installing and building:
node dist/console-demo-main.jsOpen http://127.0.0.1:8790 in a browser on the same machine. The server binds exclusively to 127.0.0.1 and serves AG Grid Community from the installed dependency.
The queue contains four fictional disputes and invoices ordered by deadline, with type and deadline filters. Records and AI explanations are explicitly simulated. Deadline filters use the fixed reference time of October 25, 2026 at 12:00 UTC.
Select an invoice and click Approve: open terminal instructions. The button saves a simulated reminder draft in demo-console.sqlite at the project root and displays its proposal ID, exact content, and review command. It records no approval and sends no reminder. Repeating the request retrieves the same stored draft. Disputes are available for review; reminder proposals apply only to invoices.
From the project root, review the returned proposal in an interactive terminal:
PAYPAL_DATABASE_PATH=./demo-console.sqlite node dist/approve-reminder.js PROPOSAL_IDReplace PROPOSAL_ID with the displayed ID. This environment-variable syntax is for POSIX shells. The CLI displays the exact proposal and requires human confirmation. Approval alone sends nothing. Keep this fictional demo database separate from the sandbox MCP database.
Reject hides an item only for the current browser session. It neither deletes a saved draft nor revokes an existing approval. The demo execution endpoint always rejects execution, including after terminal approval.
Architecture
An MCP client connects to the executable server over stdio. MCP tools expose sandbox dispute and unpaid-invoice reads, read-only priority explanations and reminder history, persistent reminder proposals, and approved reminder execution. Sandbox adapters authenticate through PayPal OAuth. SQLite stores proposals, approvals, execution attempts, and verified webhook events.
The demo console uses fictional records and a separate SQLite database through the existing ProposalStore. It has no PayPal sender and cannot record approvals.
The interactive terminal CLI lets a human review an exact proposal and approve it for 15 minutes. The MCP executor checks approval and persists an attempt before contacting PayPal, blocking repeat execution across concurrent requests and restarts. Uncertain outcomes require reconciliation. MCP exposes no approval tool.
The separate webhook receiver verifies signatures through PayPal before persistence and deduplicates deliveries durably.
Sandbox configuration
Supply configuration through the process environment:
PAYPAL_ENVIRONMENT=sandboxPAYPAL_CLIENT_IDPAYPAL_CLIENT_SECRETPAYPAL_WEBHOOK_IDPAYPAL_DATABASE_PATH=./data/operations.sqlite
See .env.example for configuration names. Load a local environment file explicitly with Node.js; the application does not load it automatically. From the project root:
node --env-file=.env --experimental-strip-types src/mcp-main.tsFor the existing MCP read acceptance command:
node --env-file=.env --experimental-strip-types src/mcp-read-acceptance.tsKeep .env private and excluded from archives. Relative paths resolve from the process working directory, so start the MCP server, webhook receiver, and approval CLI from the project root with the same database setting. Keep the sandbox database separate from the fictional demo database.
Keep credentials and real operational data out of source control, archives, and recordings. The .gitignore excludes local environment files except .env.example, dependencies, generated output, SQLite databases and their sidecar files, and the data/ directory. Ignore rules do not remove previously tracked files or sanitize archives automatically.
Run the MCP server
With sandbox configuration supplied:
node --experimental-strip-types src/mcp-main.tsThe server exposes list_disputes, list_unpaid_invoices, explain_invoice_priority, get_reminder_history, propose_invoice_reminder, and execute_invoice_reminder. See MCP-QUICKSTART.md for client setup.
Run the webhook receiver
With sandbox configuration supplied:
node --experimental-strip-types src/webhook-main.tsThe receiver listens on 127.0.0.1:8787; PAYPAL_WEBHOOK_PORT overrides the port. Configure an HTTPS reverse proxy for genuine PayPal delivery. Until PAYPAL_WEBHOOK_ID is set, it starts but rejects every delivery without storing it.
To register the webhook and trigger a genuine event:
PAYPAL_WEBHOOK_URL=https://your-host/your-path node scripts/register-webhook.mjs
# restart the receiver so it loads PAYPAL_WEBHOOK_ID
node scripts/create-webhook-test-invoice.mjsThe first script registers six invoice and dispute event types and writes the webhook ID to .env. The second creates a fictional draft invoice that is never sent; PayPal then delivers INVOICING.INVOICE.CREATED. See deploy/README.md for systemd, proxy and EnvironmentFile configuration.
Review a sandbox reminder
Use the same database setting as the sandbox MCP server and run in an interactive terminal from the project root:
node --experimental-strip-types src/approve-reminder.ts PROPOSAL_IDReview the invoice and complete message before entering the requested confirmation. Approval alone does not send a reminder. See OPERATOR-APPROVAL.md.
Submission materials
SUBMISSION.md: English Devpost submission draft.VIDEO-SCRIPT.md: recording plan targeting 2 minutes 40 seconds.evidence/ai-client-session-20261103/TRANSCRIPT.md: sanitized transcript of a recorded AI-client session (Claude Code) that called this MCP server against the PayPal sandbox on 2026-11-03, with only the four read-only tools allowed.
Label simulated footage clearly. Record genuine integration scenes only after verifying them.
License
MIT; see LICENSE.
Validation status
Verified in the PayPal sandbox on 25 and 26 October 2026: MCP reads, a human-approved reminder sent exactly once, and a genuine webhook delivery verified with PayPal, stored once and deduplicated on redelivery. The automated suite has grown to 105 tests, which run on every push in GitHub Actions on Ubuntu. Production readiness has not been established. Details in VALIDATION.md.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Invoicing you drive by talking to your AI: log time, raise invoices and track what's owed via MCP.
Create, send and track invoices from a conversation in Claude, ChatGPT or any MCP client that supports OAuth. Draft an invoice from one sentence or from last month's invoice for the same client, finalize it, email it to your client and send payment reminders for overdue ones. See revenue by month and by client, download PDFs and e-invoices (ZUGFeRD, XRechnung), and export DATEV packages for your tax advisor. Invoices follow the tax rules of 25 countries, including reverse charge and the small-business VAT exemption. New invoices are drafts, and nothing is emailed until you ask. Pay per invoice with no subscription: the first invoice is free.
Accounts receivable automation for Xero and QuickBooks Online, inside your AI assistant. Ask Claude, ChatGPT or any MCP client for a receivables summary, find customers and invoices, read the email and SMS replies your customers sent, and see what Paidnice sent or skipped. Ask why a reminder, late fee or statement did or did not go out, and update a customer's contact people straight into your ledger. Secure OAuth sign-in. One connection covers every organisation you tick, with Read or Read and Write access.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server that gives AI agents read access to subscription/SaaS invoice history, ingested from Gmail and stored in Postgres and MongoDB, with tools for listing invoices, retrieving PDFs, and summarizing spend.70 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables MCP-compatible clients to retrieve invoice and purchase order data live over stdio through tools for listing invoices, getting invoice details, and fetching purchase orders.-
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and finance teams to extract structured fields from messy invoices and audit them before payment, applying seven evidence-backed risk rules that catch total/tax mismatches, duplicate invoices, missing fields, future dates, and round amounts, then returning a 0–100 score with a payment link. Exposes four MCP tools over stdio and Streamable HTTP (spec 2025-11-25) plus a web UI, backed by an optional AWS Bedrock or OpenAI-compatible extraction brain that degrades gracefully to a zero-dependency offline engine.MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to create orders, capture payments, issue refunds and send payouts against the PayPal sandbox through four guarded MCP tools, where every call is authenticated, validated, risk-scored and policy-checked, risky actions wait for human approval, and all state changes land in a tamper-evident hash-chained audit log.MIT