mercury-multiorg-mcp

Unofficial. Not affiliated with or endorsed by Mercury.

Read-only MCP server that exposes several Mercury organizations to one AI session. A Mercury API token is created from inside a single organization, so this server holds one read-only token per org and routes every tool call by an explicit entity key.

Version 0.1.6 (see CHANGELOG.md). The maintainer tags releases as vX.Y.Z; find the commit to pin with git ls-remote --tags https://github.com/dkaleganov/mercury-multiorg-mcp 'v0.1.6^{}'. The complete tool reference with every returned field is in docs/tools.md; design notes and the build history are in the project brief on GitHub, CLAUDE.md (not shipped in the sdist).

Security model

What leaves this server falls into four classes, and the guarantees differ:

The rest of the model:

• Read-only. Only GET endpoints have client methods; the package has no code path that can move money, edit recipients, or change anything.
• Stdio only. The server never opens a network listener.
• Explicit entity. Call list_entities to discover entity keys. Every tool that accesses Mercury requires an explicit entity and identifies it in its successful result. list_entities and server_info require no entity argument. There is no default entity.
• Tokens stay in the environment. The registry names an env var per org (it must be named MERCURY_TOKEN_…, so a registry cannot point the server at some other secret); the server reads that env var and nothing else. Errors and logs never contain more than the last four characters of a token. Literal known-token scrubbing applies to values of 8 or more characters; a shorter configured value is not literal-scrubbed (the secret-token: shape scrub and the Authorization header scrub still apply, and no message quotes upstream or caller data in the first place). At startup the server warns, per entity, when a configured value does not carry Mercury's documented secret-token: prefix.
• Only Mercury hosts. --api-base / MERCURY_API_BASE must be https://api.mercury.com, https://api-sandbox.mercury.com, or a loopback mock, unless --allow-custom-api-base is passed on the command line. An inherited environment variable alone can never redirect the bearer token to another host.
• Byte limits on wire bytes. Every request declines compression (Accept-Encoding: identity). JSON/PDF reads reject nonidentity encoding before reading. Keepalive closes bodies unread. Limits are 10 MiB (10,485,760 bytes) for PDF and 32 MiB (33,554,432 bytes) for JSON, enforced on the bytes actually received while streaming. A small compressed body can no longer expand past the limit in memory. Error responses are never read at all.
• Complete or loud. Walks stop at the requested limit or API end. Missing/wrong page objects fail; optional terminal nextPage may be absent or null. Exact duplicate IDs are dropped and counted; conflicting contents fail. A page with no fresh usable rows while more are advertised fails. A walk that needs more than 200 pages fails, and a treasury cursor that is not a non-negative integer fails. Duplicate counts are reported as duplicates_dropped on every paginated result and under reportable_totals.totals, so a total is never built on a stalled, malformed, or double-counted walk.
• Windowed feeds are walked in full. Mercury documents no sort key for events or treasury transactions, so a client-side window (since on list_events, start/end on list_treasury_transactions) walks the whole bounded feed (90 days of events; the treasury ledger up to 200 pages), filters and sorts newest first here, then applies limit. truncated is exact. The cost is proportional to the feed, not the window.
• Binary documents stay in memory. PDFs come back as an embedded application/pdf blob (base64), never written to disk.
• Path ids are validated. Every id that becomes part of a request path must be a single safe segment; nothing can redirect a call to another endpoint.
• Startup errors are one line, exit 2. A missing or malformed registry (including non-string YAML keys), an unreadable file, a bad --env-file, or a disallowed API host prints one line to stderr and exits with status 2. The redacting exception hooks are installed before anything is loaded, so no startup path can print an unredacted traceback.
• Never files anything. reportable_totals is a pre-filing cross-check. Mercury has no 1099 filing endpoint; filing happens in each org's dashboard.

Hygiene. This package lives in a public repository. Tracked files, fixtures, and commit messages carry no tokens, account numbers, or financial identifiers, with two deliberate exceptions. First, the maintainer's own name appears in the package authors metadata (approved by the repository owner); business and personal names of anyone else do not appear. Second, a history note: the first Phase 1 commit's fixtures used a real, public ABA routing number as sample data; it was replaced with an obviously fake value in the next commit, so it is absent from every tagged file tree but remains in their ancestry. It identifies a bank, not an account, and the history was deliberately not rewritten. This release passed a full-history gitleaks scan.

Repository history. This package was developed in an earlier multi-project monorepo through v0.1.3 and moved to this repository at v0.1.4 with its history preserved (the same commits, rewritten to this repository's layout, so their SHAs differ from the originals). Releases up to 0.1.3 were tagged mercury-v0.1.x there and are tagged v0.1.x here; release tags are vX.Y.Z from now on. Both hygiene exceptions above apply to this history unchanged.

Install

From PyPI, running the pinned release with uvx (no clone needed):

uvx mercury-multiorg-mcp@0.1.6 --entities /private/path/entities.yaml

uvx <package>@<version> runs exactly that release in an isolated, cached environment. pip install 'mercury-multiorg-mcp==0.1.6' also works and puts mercury-multiorg-mcp and mercury-multiorg-mcp-keepalive on your PATH.

Requires Python 3.11+ and uv (for uvx).

From source / pinned commit

From a clone:

git clone https://github.com/dkaleganov/mercury-multiorg-mcp.git   # or git@github.com:dkaleganov/mercury-multiorg-mcp.git
cd mercury-multiorg-mcp
uv sync
uv run mercury-multiorg-mcp --entities /private/path/entities.yaml

Or pin a full commit SHA with uvx (pin a SHA, not a tag: a full SHA is immutable and cache-safe, while a tag can be moved):

uvx --from 'git+https://github.com/dkaleganov/mercury-multiorg-mcp@<FULL_COMMIT_SHA>' \
  mercury-multiorg-mcp --entities /private/path/entities.yaml

Configure