Skip to main content
Glama
mercury-invoicing-mcp

mercury-invoicing-mcp

🏦 mercury-invoicing-mcp

Mercury Banking MCP server with full Invoicing API support — first MCP to expose Mercury's accounts receivable endpoints.

CI CodeQL Tested with Vitest codecov OpenSSF Scorecard OpenSSF Best Practices Socket Security CodeRabbit Pull Request Reviews

npm version npm downloads Node.js Version MCP MCP Server PRs Welcome

Sponsor on GitHub Patreon Ko-fi

A Model Context Protocol (MCP) server giving AI assistants (Claude, Cursor, Continue, etc.) full programmatic access to your Mercury business banking account, including the Invoicing API (one-shot + recurring) which is missing from every other Mercury MCP.

✨ Why this MCP?

Capability

Official Mercury MCP

dragonkhoi/mercury-mcp

mercury-invoicing-mcp

Banking read (accounts, transactions, statements)

✅

✅

✅

Banking write (send_money, recipients)

❌

✅

✅

Internal transfers between your own Mercury accounts

❌

❌

✅

Invoicing API (create, update, cancel, attachments)

❌

❌

✅

Customers AR + recurring invoices

❌

❌

✅

Webhooks full CRUD (incl. update_webhook)

❌

❌

✅

Built-in safeguards (rate limit, dry-run, redacted audit log)

❌

❌

✅

Stable token (no frequent re-auth, IP-allowlistable)

❌

✅

✅

Open source (MIT)

❌

✅

✅

Node.js floor

N/A (hosted)

❌ from Node 14 EOL (2023)

✅ Active LTS (>=22.22.2)

Total tools exposed

~10

~11

34

For pure read-only consultation, prefer the official Mercury MCP. Use this one when you need to automate invoicing, write to Mercury, or expose Mercury to LLM agents safely.

Related MCP server: faxdrop-mcp

📦 Installation

npm install -g mercury-invoicing-mcp

Or use directly with npx:

npx mercury-invoicing-mcp

⚙️ Configuration

The server reads MERCURY_API_KEY from the environment. Get your API key at Mercury Settings → API Tokens.

🔑 Right-sizing the token

Mercury exposes fine-grained per-resource scopes at token creation — not a single read/write toggle. Pick exactly what your use case needs and Mercury enforces the rest server-side: a tool called without the right scope returns 403, which the MCP surfaces as a clean isError: true response (with a Mercury Plus hint when relevant).

When you create the token, you choose:

  • Which accounts the token can see (one, several, or all).

  • Read or Write per resource family: Accounts, Transactions, Recipients, Send Money, Cards, Statements, Treasury, Invoicing (AR), Webhooks.

Common scope recipes for this MCP:

Use case

Scopes to grant

Read-only consultation (dashboards, chat-channel bots)

Read on accounts, transactions, statements, cards, treasury — nothing else

Bookkeeping (categorise transactions)

Read everywhere + Write on transactions (for update_transaction)

Invoicing automation

Read on accounts + Write on invoices, customers (Mercury Plus required)

Recipients management

+ Write on recipients

Internal transfers between your own accounts

+ Write on send_money (used for create_internal_transfer)

Outbound send-money requests

+ Write on send_money (creates the request — see safety note below)

Webhooks-only ops

Write on webhooks only

⚠️ Important: outbound payments depend on YOUR Mercury approval policy

Whether an outbound payment created via this MCP executes immediately or waits for human approval is not controlled by the MCP — it is enforced by your Mercury workspace's approval policy (Settings → Approvals on app.mercury.com). The MCP can only ever create the API call; what Mercury does with it is up to your workspace configuration.

The three money tools behave differently:

  • mercury_request_send_money — always creates a pending approval request in Mercury, regardless of workspace policy. Designed for the "submit, then wait for an approver" workflow.

  • mercury_send_money — submits a payment. It executes immediately or gets queued for approval, depending on your workspace's approval rules (amount thresholds, account-specific rules, required approvers). On a workspace configured with a $0 approval threshold, every outbound payment waits for human sign-off in the Mercury web/mobile app. On a more permissive workspace, smaller payments may settle without re-prompting.

  • mercury_create_internal_transfer — moves money between two accounts you already own inside the same Mercury organisation. No external recipient, no approval workflow.

→ Set a strict approval policy in Mercury (e.g. require approval for any outbound payment, regardless of amount) if you intend to expose write tools to an agent. The MCP's per-call rate limits and dry-run mode are useful belt-and-braces, but the authoritative gate is Mercury's approval policy. If a prompt-injected agent calls send_money, the safety of that call depends entirely on what Mercury would have done if the same payload arrived from any other API caller.

🧪 Sandbox mode

To test against Mercury's sandbox environment (no real money, pre-populated dummy data), just use a sandbox token:

MERCURY_API_KEY=secret-token:mercury_sandbox_xxxxxxxxxxxxxxxx

The MCP auto-detects sandbox tokens (those starting with mercury_sandbox_) and points to https://api-sandbox.mercury.com/api/v1 automatically.

To override the base URL explicitly (e.g. for a self-hosted proxy):

MERCURY_API_BASE_URL=https://your-proxy.example.com/api/v1

🤖 Claude Desktop / Claude Code

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (or ~/.claude.json for Claude Code):

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:mercury_production_xxxxxxxxxxxxxxxx"
      }
    }
  }
}

🖱️ Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

🦀 OpenClaw

OpenClaw is an open-source self-hosted agent platform that supports MCP via @modelcontextprotocol/sdk. Add to ~/.openclaw/openclaw.json:

{
  "mcpServers": {
    "mercury-invoicing": {
      "command": "npx",
      "args": ["-y", "mercury-invoicing-mcp"],
      "env": {
        "MERCURY_API_KEY": "secret-token:..."
      }
    }
  }
}

Restart the gateway (docker restart openclaw-openclaw-gateway-1 or your equivalent). All tools become available to all your OpenClaw agents.

Tip: For agents exposed to untrusted channels (WhatsApp, Telegram, Slack, incoming email…), grant the token only the scopes the channel actually needs. Outbound payments still require explicit human approval in the Mercury app — but minimising scopes avoids noise (spurious pending requests) and reduces what an attacker could exfiltrate via reads. See Right-sizing the token for recipe per use case.

🛠️ Tools (36 total)

🏦 Banking — Accounts

  • mercury_list_accounts, mercury_get_account

  • mercury_list_cards

  • mercury_get_organization

  • mercury_list_categories

💳 Banking — IO Credit

  • mercury_list_credit_accounts — wraps GET /credit, documented under Credit › List all credit accounts in the Mercury API reference. Returns IO Credit card accounts, which mercury_list_accounts filters out server-side.

  • mercury_list_credit_transactions — wraps GET /account/{id}/transactions (SINGULAR path), the path used for IO Credit transactions including pending card authorisations. Note: distinct from the plural /accounts/{id}/transactions used for deposit accounts.

💸 Banking — Transactions

  • mercury_list_transactions, mercury_get_transaction

  • mercury_update_transaction (note, category)

  • mercury_send_money, mercury_request_send_money

  • mercury_create_internal_transfer (between your own Mercury accounts)

👥 Banking — Recipients

  • mercury_list_recipients, mercury_add_recipient, mercury_update_recipient

📊 Banking — Statements

  • mercury_list_statements

🏛️ Treasury

  • mercury_get_treasury

  • mercury_list_treasury_transactions

  • mercury_list_treasury_statements

🧾 Invoicing (Accounts Receivable)

⚠️ Mercury Plus plan required. The Invoicing & Customers (AR) APIs are only available on Mercury's Plus plan (or higher). Calls to these tools return 403 Forbidden on Free or Standard plans. The other tools (banking, treasury, webhooks) work on every plan.

  • mercury_list_invoices, mercury_get_invoice

  • mercury_create_invoice, mercury_update_invoice

  • mercury_cancel_invoice

  • mercury_list_invoice_attachments

👤 Customers (AR) — also requires Mercury Plus

  • mercury_list_customers, mercury_get_customer

  • mercury_create_customer, mercury_update_customer, mercury_delete_customer

🔗 Webhooks

  • mercury_list_webhooks, mercury_get_webhook

  • mercury_create_webhook, mercury_update_webhook, mercury_delete_webhook

Endpoints not yet wrapped — Mercury exposes ~23 additional endpoints that this MCP does not yet cover. They will land in upcoming releases. Tracked: PDF download (getinvoicepdf, getstatementpdf), attachments (uploadtransactionattachment, uploadrecipientattachment, getattachment, listrecipientsattachments), webhook signature verification (verifywebhook), webhook events (getevent, getevents), send-money approvals (listsendmoneyapprovalrequests, getsendmoneyapprovalrequest), users (getuser, getusers), Mercury Raise SAFE (getsaferequest(s), getsaferequestdocument), and OAuth flow (obtainaccesstoken, startoauth2flow).

Mercury does not expose list_send_money_requests, COA Templates or Journal Entries via the public API at all — those features are dashboard-only.

There is no send_invoice endpoint anywhere (API or dashboard). An invoice email is only sent when the invoice is created with sendEmailOption: "SendNow". To send a copy later, download the invoice PDF (Mercury UI button "Download PDF", or the getinvoicepdf endpoint — not yet wrapped, see "Endpoints not yet wrapped" above) and email it manually.

Tools available depend on your Mercury API token scope. The server registers all 34 tools but Mercury will reject unauthorized operations at the API level.

🗺️ Roadmap

See ROADMAP.md.

🔒 Security

  • Never share your API key. Use environment variables, never CLI args.

  • Use read-only or scoped tokens when you don't need write access.

  • Be aware of prompt injection risks when exposing write tools to LLMs that read untrusted content. See Anthropic's MCP security guidance.

🛡️ Built-in safeguards

This MCP includes three middleware layers that activate automatically on write tools (read tools are unaffected):

1️⃣ Rate limiting (dual-window)

Each write tool is mapped to a bucket. Every bucket enforces two rolling windows simultaneously — a daily cap (24 h) and a monthly cap (30-day rolling). A call is rejected as soon as either window is at its cap, so a runaway agent cannot drain accounts even if it stays under the daily limit by pacing itself over weeks.

Bucket

Tools

Daily

Monthly (30d)

payments

send_money, request_send_money

7

150

internal_transfer

create_internal_transfer

2

40

invoices_write

create_invoice, update_invoice

10

200

invoices_cancel

cancel_invoice

3

30

customers_write

create_customer, update_customer, delete_customer

3

60

recipients_add

add_recipient

3

45

recipients_update

update_recipient

2

15

transactions_update

update_transaction (bookkeeping, tagging, receipts)

50

500

webhooks_create

create_webhook

2

15

webhooks_update

update_webhook

2

15

webhooks_delete

delete_webhook

2

15

Override per bucket (both windows must be supplied):

MERCURY_MCP_RATE_LIMIT_payments=15/day,300/month   # larger supplier batch
MERCURY_MCP_RATE_LIMIT_invoices_write=20/day,400/month  # large monthly billing run
MERCURY_MCP_RATE_LIMIT_DISABLE=true                # disable all rate limiting (not recommended)

When exceeded, the tool returns an isError: true response with a structured JSON payload. The source and error_type prefix make it unambiguous that this is a local MCP safeguard — the call was never sent to Mercury. A genuine Mercury 429 surfaces separately as "Mercury API error 429: ...".

{
  "source": "mcp_safeguard",
  "error_type": "mcp_rate_limit_daily_exceeded",
  "message": "MCP Rate Limit Exceeded — Daily (local safeguard, not a Mercury API error)",
  "hint": "Daily Limit Exceeded: mercury_send_money (bucket: payments) capped at 7 per 24h. Retry in ~180 min. Override with MERCURY_MCP_RATE_LIMIT_payments=D/day,M/month if this is a legitimate batch.",
  "retry_after": "2026-04-22T00:00:00.000Z"
}

error_type is either mcp_rate_limit_daily_exceeded or mcp_rate_limit_monthly_exceeded — the agent learns to back off at the right granularity without confusing the MCP's local cap with a server-side Mercury limit.

The rate-limit window survives process restarts. State is persisted to ~/.mercury-mcp/ratelimit.json (mode 0o600); override the location with MERCURY_MCP_STATE_DIR=/abs/path if you need to share state between hosts or pin it to a specific volume. Without persistence, an MCP host that respawns the server per session would silently bypass the limit.

2️⃣ Dry-run mode

Inspect what an agent would do without actually calling Mercury. Useful for debugging suspected behaviour or staging:

MERCURY_MCP_DRY_RUN=true

Write tools then return a structured payload describing the intended action without hitting the Mercury API.

3️⃣ Audit log (opt-in)

Enable structured JSON logging of every write call:

MERCURY_MCP_AUDIT_LOG=/var/log/mercury-mcp-audit.log

Each line is {ts, tool, result, args} (one JSON object per line). Result is ok, dry-run, or error. The path must be absolute; sensitive fields in args (accountNumber, routingNumber, apiKey, authorization, password, token, secret, ssn) are automatically redacted. The file is created with mode 0600 (owner read/write only).

🔧 Development

git clone https://github.com/klodr/mercury-invoicing-mcp.git
cd mercury-invoicing-mcp
npm install
npm run build
npm test

💡 Inspiration

🌐 Ecosystem

Other MCP servers in the klodr family:

📄 License

MIT — see LICENSE.

🤝 Contributing

Issues and PRs welcome. See CONTRIBUTING.md for the test/build/coverage checklist and release process.

Available Tools

39 tools
mercury_add_recipientA
Idempotent

Add a new payment recipient (a counterparty you can later send money to via ACH/wire/check).

USE WHEN: onboarding a new vendor, contractor, or other payee before sending money. The returned id is what mercury_send_money and mercury_request_send_money expect as recipientId.

DO NOT USE: for AR customers (use mercury_create_customer — recipients receive money, customers pay invoices). Mercury enforces strict KYC/banking validation on bank fields — invalid routing numbers or account numbers are rejected at create time.

SIDE EFFECTS: writes a new recipient to Mercury. Persistent. Idempotent via idempotencyKey — the MCP auto-generates one if not provided, so repeated calls with the same generated key would not duplicate; pass an explicit idempotencyKey to make this stable across retries you control.

RETURNS: { id, name, status, defaultPaymentMethod, ... } — keep id for the send-money tools.

Inputs: name (required), emails (required), paymentMethod (required), idempotencyKey, +2 more.

mercury_cancel_invoiceA
Destructive

Cancel an outstanding invoice. Mercury sends a cancellation notice to the customer if the invoice was already emailed.

USE WHEN: voiding an invoice that was issued in error, that the customer disputes, or that needs to be re-issued under a corrected line-item set. ALWAYS confirm with the user before calling — the customer-facing notification is automatic.

DO NOT USE: on an invoice already paid (Mercury rejects cancellation). To refund a paid invoice, refund out-of-band via the bank, then optionally update the internal note.

SIDE EFFECTS: marks the invoice as cancelled on Mercury. The customer-facing payment URL stops accepting payments. If the invoice was emailed, Mercury notifies the customer of the cancellation by email — confirm with the user before calling. The action is logged in Mercury's audit trail. Cancellation is final from the API perspective.

RETURNS: { id, status: "cancelled", ... }.

Inputs: invoiceId (required).

mercury_create_customerA

Create a new Accounts Receivable customer (a billable entity you will later invoice).

USE WHEN: onboarding a new customer before issuing them an invoice. The returned id is what mercury_create_invoice expects as customerId.

DO NOT USE: for payment recipients (use mercury_add_recipient — different surface, used for outbound bank transfers, not invoicing).

SIDE EFFECTS: writes a new customer to your Mercury workspace. Persistent. NOT idempotent at the API level — calling twice with the same payload creates two customers; check mercury_list_customers for existing entries before creating to avoid duplicates.

RETURNS: { id, name, email, address, ... } — keep id for the invoicing tools.

Inputs: name (required), email (required), address.

mercury_create_internal_transferA
Idempotent

Move money between two of your own Mercury accounts (e.g. Checking → Savings). Funds stay inside your organisation.

USE WHEN: rebalancing cash between your own Mercury accounts — sweeping idle deposits to Treasury, funding a sub-account before issuing cards, etc. Both accounts must belong to your workspace.

DO NOT USE: to send money to an external counterparty (use mercury_send_money). To request approval-gated movement, use mercury_request_send_money (different surface, external only).

SIDE EFFECTS: moves real money between two accounts you own. Settles immediately, no approval workflow because no external recipient is involved. Persistent ledger entries on both sides. Idempotent via idempotencyKey — auto-generated if omitted, but pass an explicit one to make retries safe.

RETURNS: { id, amount, status, ... } — the booked transfer.

Inputs: amount (required), sourceAccountId (required), destinationAccountId (required), note, +1 more.

mercury_create_invoiceA

Create a new invoice (one-shot or to be sent recurrently). Requires AR write scope.

USE WHEN: billing a customer that already exists in Mercury (customerId from mercury_create_customer or mercury_list_customers). Set sendEmailOption: "SendNow" to email the invoice immediately to the customer's contact email.

DO NOT USE: when the customer does not exist yet (call mercury_create_customer first). To attach a file to the invoice, use the Mercury web app at creation time — the API attachment-upload endpoint is not exposed by this MCP currently.

SIDE EFFECTS: writes a new invoice to Mercury. Persistent. With sendEmailOption: "SendNow" (the default), Mercury also sends a real email with a payment link to the customer — confirm the customer's email and the line items before calling. Mercury Plus tier required for the AR write scope.

RETURNS: { id, status, amount, paymentUrl, ... } — paymentUrl is the Mercury-hosted page where the customer pays.

Inputs: dueDate (required), lineItems (required), customerId (required), invoiceDate (required), +12 more.

mercury_create_webhookA

Register a new webhook endpoint. Mercury will POST events as JSON to the provided URL.

USE WHEN: subscribing an external system to Mercury events (transaction.posted, invoice.paid, etc.) so you can react in near real-time without polling.

DO NOT USE: with non-HTTPS URLs, loopback / RFC 1918 / link-local / cloud-metadata IPs — the MCP enforces a defense-in-depth gate on top of Mercury's own validation to block accidental SSRF or exfiltration via prompt injection.

SIDE EFFECTS: writes a new webhook subscription to Mercury. Persistent. Once registered, Mercury immediately starts delivering matching events to your URL — make sure the endpoint is ready to receive (and ideally verify Mercury's signature). NOT idempotent at the API level — calling twice creates two subscriptions firing duplicate events.

RETURNS: { id, url, status, events, ... } — keep id for mercury_update_webhook / mercury_delete_webhook.

Inputs: url (required), events (required).

mercury_delete_customerA
Destructive

Permanently delete an Accounts Receivable customer. DESTRUCTIVE.

USE WHEN: removing a customer that was created by mistake, or that the user explicitly wants to purge. ALWAYS confirm with the user before calling — there is no undo.

DO NOT USE: when the customer has invoices in paid / outstanding status — Mercury rejects deletion in those cases and returns a 409. Cancel outstanding invoices first via mercury_cancel_invoice.

SIDE EFFECTS: permanent deletion on Mercury's side. The customer disappears from the AR list. Past invoices' customerId may dangle (Mercury does not cascade-delete invoices). NOT recoverable from API. ALWAYS confirm with the user.

RETURNS: confirmation payload from Mercury ({ deleted: true, ... } or similar).

Inputs: customerId (required).

mercury_delete_webhookA
Destructive

Delete a webhook endpoint. DESTRUCTIVE — Mercury stops delivering events to that URL.

USE WHEN: decommissioning a webhook (URL no longer reachable, integration retired, accidental duplicate). ALWAYS confirm with the user — there is no undo, and any downstream system that depended on the events stops being notified.

DO NOT USE: to temporarily silence a webhook (use mercury_update_webhook with status: "paused" instead — reversible).

SIDE EFFECTS: permanent deletion on Mercury's side. Future events that would have fired this webhook are silently dropped — no replay. Past delivery history is also lost from the Mercury dashboard.

RETURNS: confirmation payload ({ deleted: true, ... } or similar).

Inputs: webhookId (required).

mercury_get_accountA
Read-only

Retrieve details for a specific Mercury deposit account by ID.

USE WHEN: fetching the full detail of a single account whose ID is already known (typically from mercury_list_accounts). Faster than re-listing when you already have the ID.

DO NOT USE: to enumerate accounts (use mercury_list_accounts). For IO Credit accounts (use the mercury_list_credit_accounts endpoint).

RETURNS: { id, name, kind, status, availableBalance, currentBalance, accountNumber, routingNumber, ... }.

Inputs: accountId (required).

mercury_get_customerA
Read-only

Retrieve a specific Accounts Receivable customer by ID.

USE WHEN: fetching the full detail of one customer whose ID is already known. Faster than relisting + filtering when you have the ID.

DO NOT USE: to enumerate customers (use mercury_list_customers). For payment recipients use mercury_list_recipients (different surface).

RETURNS: { id, name, email, address, ... }.

Inputs: customerId (required).

mercury_get_invoiceA
Read-only

Retrieve a specific invoice by ID, including line items, status, and the payment URL.

USE WHEN: fetching the full detail of one invoice (line items, current status, balance due, payment URL) whose ID is already known.

DO NOT USE: to enumerate invoices (use mercury_list_invoices). For attachments use mercury_list_invoice_attachments.

RETURNS: { id, status, amount, customerId, lineItems, paymentUrl, dueDate, ... }.

Inputs: invoiceId (required).

mercury_get_invoice_pdfA
Read-only

Resolve the download URL of an invoice's PDF via Mercury's documented getinvoicepdf endpoint.

USE WHEN: you need the actual invoice PDF — to archive it, or to attach it to an email / bank KYB / compliance reply. mercury_list_invoice_attachments does NOT return it (that lists only files a human manually uploaded, empty on a normal invoice). This tool fetches the invoice (for its number / status / slug) and returns downloadUrl = {baseUrl}/ar/invoices/{id}/pdf, the documented endpoint (https://docs.mercury.com/reference/getinvoicepdf) that returns the PDF with Content-Disposition: attachment.

AUTH: downloadUrl is an authenticated Mercury API URL — fetch it with the same Authorization: Bearer <token> and Accept: application/pdf as every other call (it is NOT a public pre-signed link). Because it is derived from the client's configured base URL, it stays correct under the sandbox / proxy host, not just production.

DO NOT USE: for statement PDFs (use mercury_list_statements); for manually-uploaded attachments (use mercury_list_invoice_attachments). A draft invoice that was never issued may return 404 when the URL is fetched.

RETURNS: { invoiceId, invoiceNumber, status, slug, downloadUrl }.

Inputs: invoiceId (required).

mercury_get_organizationA
Read-only

Retrieve information about your Mercury organization (legal name, EIN, registered address, etc.).

USE WHEN: fetching the workspace's legal identity for invoice generation, tax documents, or to confirm which organization the API token is bound to.

DO NOT USE: for per-account info (use mercury_get_account). The Mercury API exposes only one organization per token, so there is no list variant.

RETURNS: { id, legalName, ein, address, ... }.

Inputs: no named parameters.

mercury_get_transactionA
Read-only

Retrieve a specific transaction by ID for a Mercury deposit account.

USE WHEN: fetching the full detail of one transaction whose ID is already known (typically from mercury_list_transactions). Faster than relisting + filtering.

DO NOT USE: to enumerate transactions (use mercury_list_transactions). For IO Credit transactions, use mercury_list_credit_transactions and filter by id client-side.

RETURNS: { id, amount, status, postedAt, counterpartyName, memo, attachments: [{ fileName, attachmentType }], ... } — every Mercury field, except that attachment URLs are stripped. Use mercury_get_transaction_attachment to obtain a download URL.

Inputs: accountId (required), transactionId (required).

mercury_get_transaction_attachmentA
Read-only

Obtain the pre-signed download URL(s) for a transaction's receipts / attachments.

USE WHEN: you actually intend to download a receipt — filing a supplier invoice, attaching a justification to a bookkeeping entry. Locate candidates first with mercury_list_transactions (hasAttachment: true), then call this for the one you want.

DO NOT USE: to check whether a receipt exists — mercury_list_transactions already reports hasAttachment without minting a credential. Do not call it across a whole statement to pre-fetch URLs: they expire in ~12 hours and every one you mint is a live bearer token sitting in transcripts and logs.

SIDE EFFECTS: none on Mercury (read-only). But the returned URL grants unauthenticated access to the document for ~12 hours to anyone who holds it — treat the response as a secret and do not echo it further than needed.

RETURNS: { transactionId, attachmentCount, attachments: [{ fileName, attachmentType, url }] }.

Inputs: accountId (required), transactionId (required), fileName.

mercury_get_treasuryA
Read-only

Retrieve Mercury Treasury account information (balance, current yield, eligibility, etc.).

USE WHEN: checking treasury cash balance or yield for cash-management decisions, or to confirm the workspace has Treasury enabled.

DO NOT USE: for deposit accounts (use mercury_get_account). For Treasury transactions or statements, use the dedicated list tools.

RETURNS: { id, currentBalance, yield, eligibility, ... }.

Inputs: no named parameters.

mercury_get_webhookA
Read-only

Retrieve a specific webhook endpoint by ID.

USE WHEN: fetching the full detail of one webhook (URL, current status, subscribed events) whose ID is already known.

DO NOT USE: to enumerate webhooks (use mercury_list_webhooks).

RETURNS: { id, url, status, events, ... }.

Inputs: webhookId (required).

mercury_list_accountsA
Read-only

List all deposit bank accounts in your Mercury workspace (checking, savings, treasury).

USE WHEN: enumerating Mercury bank accounts before drilling into transactions, balances, or statements. Typically the first call when you have an account ID in hand or need one.

DO NOT USE: for IO Credit card accounts (use mercury_list_credit_accounts — /credit is a separate endpoint). For a single account whose ID is already known, prefer mercury_get_account to skip the list payload.

RETURNS: { accounts: [{ id, name, kind, status, availableBalance, currentBalance, accountNumber, routingNumber, ... }] }.

Inputs: no named parameters.

mercury_list_cardsA
Read-only

List physical and virtual cards attached to a Mercury account.

USE WHEN: enumerating cards (debit, virtual debit, IO Credit) issued against an account — for spend audits, freezing review, or cardholder lookups.

DO NOT USE: to list IO Credit transactions (use mercury_list_credit_transactions). Card creation, freezing, and PIN ops are not exposed by this MCP — the Mercury API does not currently support them.

RETURNS: { cards: [{ id, last4, type, status, holderName, expiry, ... }] }.

Inputs: accountId (required).

mercury_list_categoriesA
Read-only

List transaction categories available in your Mercury workspace (e.g. Office Supplies, Meals, Travel).

USE WHEN: discovering valid categoryId values before calling mercury_update_transaction to recategorise a transaction. Also useful for category-based reporting in downstream tooling.

DO NOT USE: to list transactions in a category (use mercury_list_transactions and filter client-side). Category creation/edit is not exposed by this MCP — the Mercury API does not currently support it.

RETURNS: { categories: [{ id, name, ... }] }.

Inputs: no named parameters.

mercury_list_credit_accountsA
Read-only

List Mercury IO Credit card accounts (charge cards, distinct from deposit accounts).

USE WHEN: enumerating IO Credit accounts to find their balance, statement closing date, or to feed an ID into mercury_list_credit_transactions. Wraps GET /credit (documented under Credit › List all credit accounts in the Mercury API reference).

DO NOT USE: for deposit accounts (checking/savings/treasury) — use mercury_list_accounts, which hits a different endpoint (/accounts).

RETURNS: { accounts: [{ id, status, availableBalance, currentBalance, ... }] }.

Inputs: no named parameters.

mercury_list_credit_statementsA
Read-only

List monthly statements for a Mercury IO Credit card account. Each statement has a downloadable PDF URL.

USE WHEN: fetching IO Credit card statements for accounting, audit, or a CPA. Wraps GET /api/v2/account/{id}/statements — the v1 statements path answers 404 for credit accounts and points to this v2 endpoint. Per the Mercury changelog, statements generated after 2026-06-15 report charges as positive (amount owed) and payments as negative, with autopay as a separate line.

DO NOT USE: for deposit-account statements (use mercury_list_statements) or Treasury statements (use mercury_list_treasury_statements). The PDF URL is short-lived — re-fetch it shortly before download.

RETURNS: { statements: [{ id, startDate, endDate, endingBalance, downloadUrl, details, transactions, ... }] }.

Inputs: accountId (required).

mercury_list_credit_transactionsA
Read-only

List transactions on a Mercury IO Credit card account, including pending (not-yet-settled) card authorisations.

USE WHEN: auditing IO Credit card spend, reconciling a statement, or building a card-level transaction view. Wraps GET /account/{id}/transactions — same path Mercury exposes for deposit-account transactions; both this tool and mercury_list_transactions hit it. Supports the same filters.

DO NOT USE: for deposit-account transactions (use mercury_list_transactions). For posted transactions only, filter by status: "sent".

⚠️ Omitting start does NOT mean "all history". Mercury silently returns only a recent window — roughly the last statement period — with nothing in the response to say it truncated. Observed on a real IO Credit account: 68 transactions without start, 532 for the same card with start set. Always pass start when auditing a period, and page with offset until a call returns fewer than limit rows.

RETURNS (default detail: "compact"): { transactions: [{ id, amount, status, kind, postedAt, counterpartyName, categoryName, hasAttachment, ... }] }. pending items are card authorisations that may still be reversed. hasAttachment is always present, true or false — it answers "which card charges are still missing a receipt". Receipt URLs are never returned here; get one deliberately via mercury_get_transaction_attachment. Pass detail: "full" for every Mercury field.

Inputs: accountId (required), end, limit, start, +4 more.

mercury_list_customersA
Read-only

List Accounts Receivable customers, with cursor-based pagination.

USE WHEN: enumerating AR customers before creating an invoice (need a customerId for mercury_create_invoice), or for a customer-level audit. Use startAfter / endBefore for paging beyond the limit.

DO NOT USE: for payment recipients (mercury_list_recipients is the bank-payment counterparty list, distinct from AR customers). For one customer whose ID is known, prefer mercury_get_customer.

RETURNS: { customers: [{ id, name, email, address, ... }] }.

Inputs: limit, order, endBefore, startAfter.

mercury_list_invoice_attachmentsA
Read-only

List attachments associated with an invoice (PDF copies, supporting documents).

USE WHEN: discovering which files were attached to an invoice — for archival, audit, or to share with a customer. The download URL is short-lived; refetch shortly before download.

DO NOT USE: to upload an attachment — this MCP currently exposes only the read side. Mercury's API does support attachment upload (POST /ar/invoices/{id}/attachments); a write tool can be added if needed.

RETURNS: { attachments: [{ id, filename, downloadUrl, ... }] }.

Inputs: invoiceId (required).

mercury_list_invoicesA
Read-only

List invoices in your Mercury workspace, with cursor-based pagination.

USE WHEN: enumerating invoices for an AR audit, finding the ID of an invoice to update/cancel, or building a dunning report. Use startAfter / endBefore to page beyond the limit.

DO NOT USE: for one invoice whose ID is known (prefer mercury_get_invoice). Mercury does not currently support filtering by status or customer at the API level — filter client-side after listing.

RETURNS: { invoices: [{ id, status, amount, customerId, dueDate, ... }] }.

Inputs: limit, order, endBefore, startAfter.

mercury_list_recipientsA
Read-only

List all payment recipients (counterparties for outbound ACH/wire/check) in your Mercury workspace.

USE WHEN: enumerating recipients before sending money — need a recipientId to feed into mercury_send_money or mercury_request_send_money. Also useful for an audit of who can receive funds from this account.

DO NOT USE: for AR customers (use mercury_list_customers — different surface, different scope). Recipients are bank-payment counterparties; customers are who you invoice.

RETURNS: { recipients: [{ id, name, nickname, defaultPaymentMethod, electronicRoutingInfo, status, ... }] }.

Inputs: no named parameters.

mercury_list_statementsA
Read-only

List monthly statements for a Mercury deposit account. Each statement has a downloadable PDF URL.

USE WHEN: fetching the URL of a past statement (e.g. for accounting export, audit, or sharing with a CPA). The PDF URL is short-lived — re-fetch it shortly before download.

DO NOT USE: for IO Credit card statements (use mercury_list_credit_statements, which calls the v2 endpoint — this v1 path answers 404 for credit accounts). For Treasury statements use mercury_list_treasury_statements.

RETURNS: { page, statements: [{ id, startDate, endDate, endingBalance, downloadUrl, accountNumber, routingNumber, transactions, ... }] }.

Inputs: accountId (required), end, start.

mercury_list_transactionsA
Read-only

List transactions for a Mercury deposit account, with optional filters (date range, status, search).

USE WHEN: auditing deposit-account activity, reconciling a statement, or building a per-account ledger view. Filters server-side: status, start, end, search, limit, offset.

⚠️ Omitting start does NOT mean "all history". Mercury silently returns only a recent window — roughly the last month — with nothing in the response to say it truncated. Observed on a real account: 60 transactions without start, 391 for the same account with start set. Always pass start when auditing a period, and page with offset until a call returns fewer than limit rows.

DO NOT USE: for IO Credit transactions (use mercury_list_credit_transactions, which targets the IO Credit account surface). For Treasury, use mercury_list_treasury_transactions.

RETURNS (default detail: "compact"): { transactions: [{ id, amount, status, kind, postedAt, counterpartyName, categoryName, hasAttachment, ... }] }. hasAttachment is always present, true or false — it answers "which transactions are still missing a receipt". Receipt URLs are never returned here (a pre-signed S3 URL is ~2.4 kB and is a 12-hour bearer credential); get one deliberately via mercury_get_transaction_attachment. Pass detail: "full" for every Mercury field.

Inputs: accountId (required), end, limit, start, +4 more.

mercury_list_treasury_statementsA
Read-only

List monthly statements for a Mercury Treasury account.

USE WHEN: fetching the URL of a past Treasury statement for tax/audit export. PDF URL is short-lived — fetch it shortly before download.

DO NOT USE: for deposit-account statements (use mercury_list_statements). For IO Credit card statements use mercury_list_credit_statements.

RETURNS: { statements: [{ id, periodStart, periodEnd, downloadUrl, ... }] }.

Inputs: accountId (required).

mercury_list_treasury_transactionsA
Read-only

List transactions for a Mercury Treasury account (sweeps, dividend accruals, etc.).

USE WHEN: auditing Treasury cash flows, reconciling yield accruals, or building a Treasury-only ledger view.

DO NOT USE: for deposit-account transactions (use mercury_list_transactions). For IO Credit transactions, use mercury_list_credit_transactions.

⚠️ This endpoint has no date filter. Unlike mercury_list_transactions, Treasury accepts only limit, order and cursor — there is no start/end. To audit a period, page through the transactions and filter on canonicalDay (the Treasury row date, YYYY-MM-DD) yourself.

⚠️ Pagination is cursor-based, not offset-based. Pass the top-level cursor of the response as the cursor of the next call, and stop when it is null or absent — a short page is not the end signal. Passing an offset does nothing — Mercury ignores it and you silently re-read page 1.

RETURNS (default detail: "compact"): { transactions: [{ id, type, description, amount, balance, canonicalDay, security, details, ... }], cursor } — null fields omitted. Pass detail: "full" for every Mercury field (accountId, null fields).

Inputs: accountId (required), limit, order, cursor, +1 more.

mercury_list_webhooksA
Read-only

List all webhook endpoints configured for your Mercury workspace.

USE WHEN: enumerating registered webhook endpoints — for audit, finding a webhook ID before update/delete, or to confirm a delivery target is registered.

DO NOT USE: to inspect webhook delivery history (Mercury exposes that only via the dashboard, not the API).

RETURNS: { webhooks: [{ id, url, status, events, ... }] }.

Inputs: no named parameters.

mercury_request_send_moneyA
DestructiveIdempotent

Request to send money — Mercury creates a pending approval request that a human must approve before any funds move. ALWAYS creates an approval request, regardless of workspace policy.

USE WHEN: submitting an outbound payment that should always wait for human sign-off — for safety, audit, or because workspace policy demands it. Pairs naturally with the "submit, then wait for approver" workflow.

DO NOT USE: when you intend to transfer between your own accounts (use mercury_create_internal_transfer — no external recipient). For payments that may execute immediately under workspace policy, use mercury_send_money (different surface).

SIDE EFFECTS: creates a pending approval request on Mercury — no money has moved at this point. A human approver must sign off in the Mercury web/mobile app. Once approved, Mercury executes the underlying ACH / wire / check. Idempotent via idempotencyKey — auto-generated if not passed; pass an explicit one to make retries safe. Audit log entry on Mercury for the request itself.

RETURNS: { id, status: "pendingApproval", amount, ... } — track via mercury_get_transaction once executed.

Inputs: amount (required), accountId (required), recipientId (required), paymentMethod (required), +3 more.

mercury_send_moneyA
DestructiveIdempotent

Send money from a Mercury account to an external recipient via ACH, wire, or check. REAL FUNDS LEAVE YOUR ACCOUNT.

USE WHEN: paying a vendor / contractor / counterparty whose recipientId already exists. ALWAYS confirm amount, recipient name, and payment method with the user before calling — the action is high-impact and largely irreversible (wires especially).

DO NOT USE: to move money between your own Mercury accounts (use mercury_create_internal_transfer). To submit a payment that ALWAYS requires human approval regardless of workspace policy, use mercury_request_send_money instead.

SIDE EFFECTS: moves real money out of the account. Whether the payment executes immediately or queues for approval depends entirely on your Mercury workspace's approval policy (Settings → Approvals on app.mercury.com) — the MCP cannot enforce this; Mercury does. On a $0-threshold workspace every send waits for sign-off; on a permissive workspace small payments may settle without re-prompting. Wires are usually irreversible once executed. Idempotent via idempotencyKey — auto-generated if not passed; pass an explicit one to make retries safe. Audit log entry on Mercury.

RETURNS: { id, status, amount, ... }. status reflects either immediate execution or pending-approval state, depending on workspace policy.

Inputs: amount (required), accountId (required), recipientId (required), paymentMethod (required), +3 more.

mercury_update_customerA

Update an existing Accounts Receivable customer. Pass only the fields you want to change.

USE WHEN: amending a customer's contact details (name, email, billing address) after creation. Existing invoices are not retroactively modified.

DO NOT USE: to delete a customer (use mercury_delete_customer). To change the customer of an existing invoice, cancel + recreate the invoice.

SIDE EFFECTS: writes the new customer record to Mercury. Persistent. Only the fields you pass are changed — omitted fields keep their current value.

RETURNS: { id, name, email, address, ... } — the updated customer.

Inputs: customerId (required), name, email, address.

mercury_update_invoiceA

Update an existing invoice. Pass only the fields you want to change.

USE WHEN: amending an outstanding invoice (line items, due date, memo, PO number) before the customer pays. The MCP fetches the current invoice and merges your changes before submitting — Mercury's update endpoint requires the full payload despite the API docs implying PATCH.

DO NOT USE: to cancel an invoice (use mercury_cancel_invoice). To change the customer or the destination account, cancel + recreate. Once an invoice is paid, updates are likely rejected by Mercury — fetch first to confirm status.

SIDE EFFECTS: overwrites the invoice on Mercury's side. The customer-facing payment URL stays the same. If the invoice was already emailed, the customer is NOT re-notified of the change — communicate the change out-of-band if needed.

RETURNS: { id, status, amount, ... } — the updated invoice.

Inputs: invoiceId (required), dueDate, ccEmails, poNumber, +5 more.

mercury_update_recipientA

Update an existing payment recipient (legal name, nickname, contact emails, default payment method).

USE WHEN: amending a recipient's contact info or default payment method after creation. Useful for re-routing future payments to a recipient via a different method (e.g. ACH → wire) without recreating it.

DO NOT USE: to change the bank account number / routing number — that requires a fresh recipient (security policy on Mercury's side). Use mercury_add_recipient for the new banking info.

SIDE EFFECTS: writes the recipient record on Mercury. Persistent. Only the fields you pass are changed. Mercury endpoint is POST /recipient/{id} (SINGULAR — not the plural /recipients/{id}).

RETURNS: { id, name, nickname, defaultPaymentMethod, ... } — the updated recipient.

Inputs: recipientId (required), name, emails, nickname, +2 more.

mercury_update_transactionA

Update a transaction's internal note or category (no money movement).

USE WHEN: tagging a transaction with a category for bookkeeping, or attaching an internal memo. Send null to clear a field, omit the key to keep the current value.

DO NOT USE: to change the amount, counterparty, or status — those are immutable post-execution. Mercury endpoint is PATCH /transaction/{id} (no accountId in the path).

SIDE EFFECTS: overwrites the note / category on Mercury's side. Persistent. Audit log on Mercury records the change. No effect on the booked transaction itself or on the counterparty.

RETURNS: { id, note, categoryId, ... } — the updated transaction, with attachment URLs stripped (use mercury_get_transaction_attachment for a download URL).

Inputs: transactionId (required), note, categoryId.

mercury_update_webhookA

Update an existing webhook endpoint (URL, status, or subscribed events).

USE WHEN: rotating a webhook's destination URL, changing the event subscription, or reactivating a webhook Mercury auto-disabled after consecutive delivery failures (set status: "active").

DO NOT USE: to inspect delivery history. Same SSRF / non-HTTPS URL guard as mercury_create_webhook applies to the new URL.

SIDE EFFECTS: overwrites the webhook record. Persistent. If status flips to active, Mercury resumes delivery on the next matching event. The new URL takes effect immediately for future events.

RETURNS: { id, url, status, events, ... } — the updated webhook.

Inputs: webhookId (required), url, status, eventTypes.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.3/5.0

    Scored across 39 tools

    Disambiguation4/5

    The tool set is generally well separated by resource surface: deposit accounts, IO Credit accounts, Treasury, recipients, customers, invoices, statements, and webhooks each have dedicated tools. The many list/get pairs and three statement variants could be confused, but the descriptions consistently clarify boundaries with DO NOT USE notes. A few similar tools (e.g. mercury_list_transactions vs mercury_list_credit_transactions vs mercury_list_treasury_transactions) require careful reading but are distinguishable.

    Naming Consistency4/5

    Almost all tools use a consistent mercury_ prefix and snake_case verb_noun pattern. Minor deviations exist, such as mercury_add_recipient vs mercury_create_customer and mercury_request_send_money, but these are still readable and predictable. No chaotic mixing of camelCase or vague verbs.

    Tool Count2/5

    Thirty-nine tools is heavy for the apparent scope, even for a broad Mercury banking/invoicing surface. The set covers many distinct resources, but the sheer number of list/get/create/update/cancel/delete variants makes discovery and selection costly. A more consolidated or grouped surface would likely be easier to use.

    Completeness4/5

    Core workflows are well covered: accounts, transactions, statements, customers, invoices, recipients, webhooks, cards, categories, Treasury, and payments. There are some notable gaps, such as no recipient delete, no invoice attachment upload, and limited card lifecycle operations, but most are explicitly documented as API or MCP limitations. Agents can work around the remaining gaps for typical invoicing and banking tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      A Model Context Protocol server implementation providing standardized access to Xero's accounting and business features, enabling operations like contact management, invoice creation, and chart of accounts management through MCP.
      51
      21,642 npm
      394
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to send real faxes through the FaxDrop API. Provides safeguards including rate limiting, dry-run mode, and audit logging for secure fax operations.
      3
      99 npm
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Simple MCP server that interfaces with the Mercury API, allowing you to talk to your Mercury banking data from any MCP client like Cursor or Claude Desktop.
      4
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      A custom MCP server for the Mercury banking API that uses personal API tokens to avoid session expiry. It provides 15 tools for managing accounts, transactions, recipients, treasury, and more.
      15
      MIT