# expense tracker [Health: Active]

**Category:** 💰 Finance & Fintech  
**Repository:** https://github.com/theluckystrike/mcp-expense-tracker  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/expense-tracker

## Description
Local expenses, receipts and mileage ledger for freelancers: categorise, split VAT, summarise, export to CSV or xlsx and rebill straight into an invoice.

## Tools
Capabilities this server exposes over MCP:

- **expense_add** — Log one expense: amount, currency, category, merchant, date, project, note, receipt path, billable flag, VAT rate. An empty category is filled in from the merchant rules. `billable` defaults to **true when a `project` is given** and false otherwise, and the response always states which value was us…
- **expense_settings** — Read or set the defaults `expense_add` uses when a call names none: `default_vat_rate`, `default_currency
- **expense_list** — List expenses in a date range, filtered by project, category or billable, with totals per currency
- **expense_update** — Change any field of a stored expense by id. `rebilled: false` clears both the rebilled marker and the invoice number. Amount, currency and `vat_rate` are refused on an expense already rebilled unless you pass `unlink_rebill: true`, which clears the rebill link, because the invoice charged something…
- **expense_delete** — Delete one expense by id. The receipt file itself is left alone
- **receipt_attach** — Attach a receipt file to an expense. The file must exist; its path and sha256 are stored
- **category_rules** — Set or list the merchant-to-category rules. A match with no regex metacharacters is a plain substring; one with them is compiled only if it cannot backtrack exponentially, and a pattern like `(a+)+` is refused
- **expense_summary** — Totals for a range grouped by category, project, month or merchant, with the gross, net and VAT per currency
- **mileage_add** — Log a trip in km or miles and price it from the rate table (or your own rate)
- **expense_export** — Write the range to csv, xlsx or json and return the path. Never writes a partial file
- **expense_to_invoice** — Preview a project's unbilled billable expenses as `invoice_create` line items, per currency, with an optional markup and an optional `assume_vat_rate`. Pass `target_currency` + `fx_rates` to fold every currency into one group. When nothing matches it returns `count: 0`, no `fx_note`, and the plain…
- **expense_mark_rebilled** — Mark expenses rebilled once the invoice exists, by ids or by project, date range and `currency`. `invoice_number` is required
- **license_status** — Show free or Pro mode
- **license_activate** — Activate a Pro key (verified offline)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "expense-tracker": {
    "command": "npx",
    "args": ["-y","@theluckystrike/mcp-expense-tracker"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/expense-tracker/readme_