Expense tracker

What the expense tracker MCP server does

The expense tracker MCP server maintains a local ledger for business expenses, receipts, and mileage. It is intended for freelancers and other users who need to record costs by project, category, merchant, date, currency, and billable status without sending ledger data to an expense SaaS. Records are stored in a plain JSON file on the local machine.

Expenses can include a receipt path, VAT rate, notes, and project information. When no category is supplied, merchant rules can provide one. Billable status defaults to true when an expense has a project and false otherwise, and the tool response reports the value used. Mileage entries are priced using a regional approximation table or a rate supplied by the caller.

The expense tracker MCP server can prepare unbilled billable project expenses as invoice line items. It previews those items rather than marking them as rebilled; a separate tool records the invoice number after the invoice exists.

How it works

MCP clients call tools to create, inspect, update, and remove ledger records. Listing and summary operations accept date ranges and can filter or group by project, category, billable status, month, or merchant. Totals remain separated by currency, with gross, net, and VAT values available in summaries.

Receipts are attached by an existing file path. The ledger stores the path and a SHA-256 hash, while deleting an expense leaves the receipt file itself untouched. Export writes a complete CSV, XLSX, or JSON file and returns its path.

Invoice preparation can apply a markup, assume a VAT rate, or convert multiple currencies when a target currency and exchange-rate mapping are supplied. Rebilling requires an invoice number and can target selected expense IDs or a project and date range.

Setup and configuration

A hosted deployment is available at https://mcp.zovo.one/mcp/expense-tracker using streamable HTTP and a bearer token. Clients that cannot set headers can place the token in the URL path. A token is required for tool calls to the hosted endpoint.

For local use, download the Claude Desktop .mcpb bundle or clone the repository, install dependencies, and build it with npm. The resulting MCP entry point is dist/index.js, which can be started with Node and an absolute path in the client's MCP configuration. The package is not currently published on npm, so the documented npx setup should not be treated as available until publication.

expense_settings controls the default currency and VAT rate used when an expense omits them. Set MCP_LICENSE_KEY in the client configuration or call license_activate to use Pro mode; free and Pro status can be checked with license_status.

Tools and capabilities

• Add, list, update, and delete expenses.
• Attach receipts and retain their SHA-256 hashes.
• Define merchant-to-category rules with safeguards against unsafe regular expressions.
• Record mileage in kilometres or miles using a table rate or custom rate.
• Summarise expenses by category, project, month, or merchant.
• Export a date range to CSV, XLSX, or JSON.
• Preview invoice line items and mark expenses as rebilled.

The server also exposes an expenses://month resource for current-month totals and supports a monthly_close prompt covering totals, uninvoiced billable expenses, and expenses without receipts.

Limitations and notes

Mileage table values are approximations, not tax calculations. They do not vary by year, vehicle, or threshold, so users needing an exact allowance should supply their own rate. With no region, miles use the US table rate and kilometres use the EU table rate.

Totals are not mixed across currencies unless a target currency and exchange rates are explicitly provided for invoice preparation. Editing amount, currency, or VAT on a rebilled expense requires unlinking the rebill first. Receipt attachment requires the referenced file to exist, and deleting an expense does not delete that file.