What it is
@paymentsnp/mcp is a small MCP server that runs on your own computer and talks to the Paymentsnp API with a key you give it. Your assistant can then look things up for you instead of you exporting a CSV.
| Run | npx -y @paymentsnp/mcp |
|---|---|
| Runtime | Node.js 20 or newer |
| Size | One file, no dependencies |
| Transport | stdio, started by your MCP client |
| Default mode | Read-only. Write tools appear only when you turn them on. |
| Clients | Claude Code, Claude Desktop, Cursor and other desktop MCP clients |
Because npx fetches it on demand, there is nothing to install. For offline machines, download the ZIP from Dashboard > Downloads and run node /path/to/paymentsnp-mcp/server.js instead.
1. Create an API key
In the dashboard, switch to Test, open API keys and create a key for the assistant. Tick only the scopes for the tools you want it to have.
| Tools | Scope | Kind |
|---|---|---|
get_checkout_session | checkout:read | Read |
list_payments, get_payment, payments_summary, list_refunds | payments:read | Read |
list_invoices, get_invoice | invoices:read | Read |
reconciliation_report | reconciliation:read | Read |
create_checkout_session, expire_checkout_session | checkout:create | Write |
create_invoice_draft, finalize_invoice, send_invoice | invoices:write | Write |
record_refund | refunds:write | Write |
The key decides the environment: an np_test_ key sees only test data, an np_live_ key only live data. Start with a test key. For a live key, consider an IP allowlist and a short expiry.
2. Add it to your client
claude mcp add paymentsnp --env PAYMENTSNP_API_KEY=np_test_xxx -- npx -y @paymentsnp/mcp// Settings > Developer > Edit Config (claude_desktop_config.json)
{
"mcpServers": {
"paymentsnp": {
"command": "npx",
"args": ["-y", "@paymentsnp/mcp"],
"env": { "PAYMENTSNP_API_KEY": "np_test_xxx" }
}
}
}// ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project)
{
"mcpServers": {
"paymentsnp": {
"command": "npx",
"args": ["-y", "@paymentsnp/mcp"],
"env": { "PAYMENTSNP_API_KEY": "np_test_xxx" }
}
}
}Restart Claude Desktop after editing its config. If Node is not on its PATH, use the absolute path to npx (which npx).
Questions to ask
- "How much did we receive through Khalti this week?"
- "Which invoices are overdue, and what is the total?"
- "Show the payment for order ORD-1001 and its provider transaction ID."
- "Compare verified payments with imported settlements for the last 30 days."
- "Is checkout session c1a94d07 paid yet?"
Every *_minor amount comes with a formatted twin, for example amount_npr: "NPR 1,500.50", so the assistant does not have to convert paisa itself.
Tools
Read, always available
get_checkout_session: status of a checkout session.list_payments: verified payments, with limit, offset, search, provider and Nepal dates.get_payment: one payment with its provider transaction ID.payments_summary: verified gross, count and pending attempts. Not a balance; money settles directly to your provider accounts.list_refunds: refunds recorded for one payment.list_invoicesandget_invoice: invoices by status or search, with totals and recent timeline events.reconciliation_report: verified payments against imported settlements for 7, 30 or 90 days.
Write, only with PAYMENTSNP_MCP_ALLOW_WRITES=true
create_checkout_sessionandexpire_checkout_session. The order ID is the Idempotency-Key, so asking twice returns the same checkout.create_invoice_draft,finalize_invoiceandsend_invoice.record_refund: records a refund you already made in the provider panel. It moves no money, and asking twice records once.
There are no payout, automatic refund or delete tools.
Settings
| Variable | Default | Effect |
|---|---|---|
PAYMENTSNP_API_KEY | Required | Your np_test_ or np_live_ key. Read from the environment only, never echoed back. |
PAYMENTSNP_MCP_ALLOW_WRITES | false | true adds the write tools. |
PAYMENTSNP_MCP_SHOW_PII | false | true shows customer emails and phone numbers unmasked. |
PAYMENTSNP_API_BASE_URL | https://api.paymentnp.com/v1 | Must be https; plain http only for localhost. |
Safety notes
- Your key stays local. It is read from your client's config and sent only to the Paymentsnp API.
- Masked by default. Customer emails and phone numbers appear as
s***@example.comand98******78. - Data, not instructions. Names, descriptions and memos were typed by customers or staff. The assistant should treat them as data.
- Least privilege. Give the key read scopes only unless you need writes, and prefer a test key while you try it.
The server speaks MCP over stdio with JSON-RPC 2.0. Errors use the same class names as the SDKs, with the API's error code and request ID.