Billy MCP
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| BILLY_DATA_DIR | No | Optional: use a different data directory for separate account profiles. | |
| BILLY_ACCESS_TOKEN | No | Billy API access token. If not provided, the server loads credentials.env from ~/.local/share/billy-mcp/. | |
| BILLY_ALLOW_WRITES | No | Set to 'true' to enable write capabilities (off by default). | |
| BILLY_ORGANIZATION_ID | No | Optional: set to enforce an expected company ID in addition to the token. | |
| BILLY_ALLOW_BANK_MATCHING | No | Set to 'true' to enable bank matching operations (defaults to false). |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| billy_statusB | Configuration and connection status. Never exposes credentials. |
| billy_listA | List every page of a Billy resource. Default response is compact and complete; verbose returns sanitized detail. Unknown filters are rejected. |
| billy_getA | Read a Billy record and optionally sideload relationships. Default response is compact; verbose returns sanitized detail. |
| billy_period_overviewA | Inventory unreconciled bank lines, existing postings, bills and collected receipts for a period. Candidate matches are suggestions, not an accounting verdict. |
| billy_trial_balanceB | Balances by live account through an inclusive posting entry date. Uses base currency and rejects FX postings without a base amount. |
| billy_profit_lossA | Period P&L from non-voided postings. Defaults to live incomeStatement account natures, or accepts explicit reportType or revenue and expense account IDs; no chart numbers are assumed. |
| billy_outstandingA | Current approved unpaid bills and invoices, grouped by original currency. Not a historical as-of report. |
| billy_period_expensesB | Net expense postings on debit-normal accounts under a live account-nature reportType (default incomeStatement), optionally narrowed to selected expense account IDs; credits reduce expense. |
| billy_import_receiptB | Archive an original PDF/PNG/JPEG from the configured inbox. Provide extracted invoice metadata and provenance from Gmail, Drive, local files or vendor portal. Same bytes are deduplicated. Does not upload to Billy. |
| billy_receiptsC | List locally archived supporting documents and their Billy attachment IDs. |
| billy_save_vendorA | Store a vendor billing portal location and retrieval status. This registry guides the agent browser/connector; it does not log in itself. Never include secrets or session URLs. |
| billy_vendorsB | List vendor billing portals and access exceptions for receipt retrieval. |
| billy_prepareB | Validate and persist a concrete write proposal without modifying Billy. Review the returned operation, reason, ID and hash. Receipts must be uploaded before preparing a booking. Reconciliation is restricted to matching existing bank-account postings. |
| billy_planB | Inspect a saved proposal and its execution evidence. Default output retains operation, hash and snapshot hashes. |
| billy_refresh_planA | Refresh an unexecuted/rejected proposal after changed data or expiry; review it again before execution. |
| billy_executeA | Execute the exact reviewed proposal once. Default approval uses the MCP client form; a supplied authorization note is only an audit assertion. Unknown outcomes block further writes. |
| billy_batch_prepareA | Preflight and save an ordered purchase batch (1-10 cases). Each case binds an original receipt, exact draft lines and explicit approval/payment/reconciliation stages. No Billy writes. |
| billy_batch_getB | Inspect saved batch, child plan IDs, partial progress and stop reason. |
| billy_batch_refreshA | Refresh initial evidence for a batch before any stage starts; clears prior client approval. |
| billy_batch_executeA | Approve the complete ordered company batch once and execute its stages sequentially through guarded plans. A stop returns explicit partial progress. Resume the same hash after inspecting the cause. |
| billy_journalA | Read the last 200 proposals, including rejected/uncertain writes. An unknown outcome requires reconciliation against live Billy records before recovery. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| bookkeeping-period | Bookkeeping workflow: gather receipts from mail/files/vendor accounts, propose bookings, reconcile and verify. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 21 tools
The toolset separates generic reads, financial reports, receipt/vendor management, and proposal/batch write workflows. Some overlap exists among the reporting tools and between refresh_plan/batch_refresh or plan/batch_get, but the descriptions are specific enough to guide selection.
All tools share the billy_ prefix and snake_case, but the action pattern is inconsistent: bare verbs, noun phrases, verb_noun, and object_verb forms are mixed. This is readable but lacks a uniform verb_noun convention.
21 tools is on the heavy side and spans multiple subdomains such as reporting, receipts, vendors, single proposals, and batches. Each tool appears purposeful, but the count is at the borderline where agents may have trouble finding the right tool.
The surface covers status, generic reads, financial reports, receipt archival, vendor registry, single-plan lifecycle, and batch lifecycle, with a journal for recovery after unknown outcomes. Minor gaps like explicit cancellation/voiding or direct upload-to-Billy are not clearly exposed, but the proposal workflow avoids dead ends.