# Log expenses from Claude with a free MCP server

<!-- mirror-seo:start -->

**MCP server for expense tracking: track business expenses, receipts and mileage with an expense tracker.** Receipts, mileage and expenses that turn into invoice lines.

Works with Claude Desktop, Claude Code, Cursor and any Model Context Protocol client. Runs on your own machine, or hosted with no install.

Product page: <https://mcp.zovo.one/s/expense-tracker> — capabilities, free limits and supported installation paths.

## Install

**Hosted, nothing to install.** Get a token from <https://mcp.zovo.one/mcp/connect?acq=github> (the connect page) or <https://mcp.zovo.one/mcp/token> (the same token as JSON); a free anonymous one is issued on the spot and a Pro key works the same way. Then point an MCP client at `https://mcp.zovo.one/mcp/expense-tracker` over streamable-http and send the token as `Authorization: Bearer <token>`.

If your client cannot set headers, put the token in the path instead: `https://mcp.zovo.one/mcp/expense-tracker/t/<token>`. Both forms work. The bare URL with no token answers 401 on `tools/call`, so the token is not optional.

**Claude Desktop, one click.** Download `expense-tracker.mcpb` from the [bundle catalog](https://mcp.zovo.one/downloads#expense-tracker) and double-click it.

**From source.** The mirror is self-contained: every `@theluckystrike/*` dependency is vendored, so a fresh clone builds with no extra setup.

```sh
git clone https://github.com/theluckystrike/mcp-expense-tracker.git
cd mcp-expense-tracker
npm install && npm run build
```

Then point your client at the built entry point:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-expense-tracker/dist/index.js"]
    }
  }
}
```

> `@theluckystrike/mcp-expense-tracker` is **not published on npm yet**, so an `npx -y @theluckystrike/mcp-expense-tracker` command will fail. The three paths above are the working ones and each is exercised by CI.

![expense-tracker demo](https://raw.githubusercontent.com/theluckystrike/mcp-servers/main/assets/demo-expense-tracker.gif)

Read-only mirror of [mcp-servers/servers/expense-tracker](https://github.com/theluckystrike/mcp-servers/tree/main/servers/expense-tracker). See [MIRROR.md](MIRROR.md).

<!-- mirror-seo:end -->

**In the [official MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.theluckystrike%2Fexpense-tracker-receipts-mileage/versions/latest)** (`io.github.theluckystrike/expense-tracker-receipts-mileage`).


Say "12.30 euros at Adobe, software, billable to Acme" and it is logged, categorised, VAT-split and ready to rebill. This MCP server keeps a local ledger of your business expenses: every amount is held in integer minor units in its own currency, `vat_rate` splits the gross on the receipt into net and VAT (set it once with `expense_settings` and every later expense is split without repeating it), merchant rules categorise new expenses on their own, receipts are attached by path and sha256 so an audit can prove the file has not changed, and business trips are priced from a built-in mileage table. Summaries group by category, project, month or merchant, always per currency and never mixed. It exports to CSV, xlsx or JSON, and `expense_to_invoice` hands the billable expenses of a project to `mcp-invoice` in exactly the line-item shape `invoice_create` expects. Everything is stored in a plain JSON file on your own machine; nothing is uploaded anywhere.

Log receipts and mileage in chat, split the VAT, and rebill them onto an invoice, no expense SaaS required.

## 60-second install

Use [**expense-tracker.mcpb v0.22.9**](https://github.com/theluckystrike/mcp-servers/releases/download/v0.22.9/expense-tracker.mcpb) in Claude Desktop. [Published checksums](https://github.com/theluckystrike/mcp-servers/releases/download/v0.22.9/SHA256SUMS.txt) and the [versioned download catalog](https://mcp.zovo.one/downloads#expense-tracker) identify the exact release. The npm package is not published.

For a source installation, use Node.js 22 or newer and build the shared dependency first:

```sh
git clone https://github.com/theluckystrike/mcp-servers.git
cd mcp-servers
npm ci
node scripts/bootstrap-timezone.mjs
npm run build -w packages/mcp-license -w servers/expense-tracker
```

Merge this entry into Claude Desktop's `mcpServers`, or into `.cursor/mcp.json` for Cursor. Replace the absolute path with your checkout:

```json
{
  "mcpServers": {
    "expense-tracker": {
      "command": "node",
      "args": ["/absolute/path/mcp-servers/servers/expense-tracker/dist/index.js"]
    }
  }
}
```

For Claude Code:

```sh
claude mcp add expense-tracker -- node /absolute/path/mcp-servers/servers/expense-tracker/dist/index.js
```

To run in Pro mode set `MCP_LICENSE_KEY` in the same config block, or call `license_activate` once with your key.

## Tools

| Tool | What it does |
| --- | --- |
| `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 used |
| `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 else |
| `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 reason. Marks nothing as rebilled, ever |
| `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) |

Resource: `expenses://month` returns the current calendar month's totals by category, per currency.

Prompt: `monthly_close` walks the month's totals, the billable expenses not yet invoiced, and the expenses with no receipt attached.

## Mileage rates

The table holds one flat rate per region. Each row is an approximation with a stated assumption, not a tax calculation:

| Region | Rate | Unit | Currency | What it assumes |
| --- | --- | --- | --- | --- |
| PL | 1.15 | km | PLN | A car over 900 cm3. The Polish limit is PLN 0.89/km up to 900 cm3, and there are separate motorcycle and moped rates |
| UK | 0.45 | mile | GBP | A car, within the first 10,000 business miles of the tax year. HMRC pays a lower rate above that threshold, and different rates for motorcycles and bicycles |
| US | 0.70 | mile | USD | The IRS business standard rate for one calendar year. The IRS re-issues it every year, and has changed it mid-year |
| EU | 0.30 | km | EUR | A generic per-kilometre allowance. There is no single EU rate; each member state sets its own |

There are deliberately no year, vehicle or threshold tables behind these numbers: a table that looks authoritative but is a year out of date is worse than one that says what it is. Every `mileage_add` reply names the rate it used and repeats that caveat, for example `(table rate PL 1.15 PLN/km, an approximation; pass rate_per_km for your exact scheme)`.

With no `region`, miles use the US rate and kilometres the EU rate. `rate_per_km` overrides the table with your own rate for the unit you passed, which is the supported way to claim an exact scheme (an engine class, a mid-year rate, the band above 10,000 miles). `currency` is only accepted **together with** `rate_per_km`: a table rate is quoted in its own currency, and relabelling PLN 1.15/km as EUR 1.15/km would convert nothing and book roughly four times the real cost, so that call is refused.

## Pairs with the rest of the collection

`expense_to_invoice` returns `{description, quantity, unit_price, tax_rate}` objects, which is exactly the `items` array [mcp-invoice](../invoice) takes. `unit_price` is the net amount, `tax_rate` is the VAT rate recorded on the expense, so the invoice recomputes the same tax rather than double-charging it, and the line total comes back to the gross on the receipt. Where rounding the tax a second time cannot reproduce that gross (EUR 0.03 at 23% splits into 0.02 + 0.01, but 0.02 taxed at 23% rounds to 0.00), the `unit_price` is nudged by the one cent if that lands the invoice exactly, and otherwise the group carries a visible `[rounding adjustment ...]` line at `tax_rate: 0`; `rounding_adjustment_lines` counts them.

### Mixed currencies

One invoice carries one currency, so a week of USD hours, a EUR receipt and a GBP mileage line comes back as three groups. To get a single invoice, supply the target and your own rates:

```
expense_to_invoice {project: "Nova", from: "2026-09-01", to: "2026-09-07",
                    target_currency: "USD", fx_rates: {"EUR": 1.08, "GBP": 1.27}}
```

`fx_rates` reads as "1 unit of that currency = X units of `target_currency`". Every line is converted and one group is returned, and each converted line says so on its own face: `... [converted from EUR 12.40 at 1.08]`. Nothing here fetches or invents a rate; a currency with no rate is refused by name. Without `fx_rates`, a mixed range returns the exact call to make instead of leaving you to work it out.

A stored `vat_rate` of `0` is a rate, not a gap: an exempt receipt stays exempt. An expense recorded with **no** rate holds a gross amount, and it is rebilled as-is with `tax_rate: 0` and `tax_rate: 0 (VAT unknown, gross rebilled as-is; pass assume_vat_rate to split)` in the description, so a default rate on the invoice cannot tax the receipt twice. The `expense_settings` default is applied when the expense is **inserted** and never retroactively at rebill time: changing that default later must not rewrite the tax meaning of receipts entered before it existed. To split those older lines anyway, pass `assume_vat_rate` explicitly on the `expense_to_invoice` call and the lines are flagged `[vat assumed 23%]`.

Nothing is marked rebilled by that call, and there is no option to make it: create the invoice first, then call `expense_mark_rebilled` with a required `invoice_number`. Because one invoice carries one currency, the result is grouped per currency, each group carries its own `expense_ids`, and you pass one group. Marking by ids is the precise route; marking by project and date range additionally **requires** `currency`, and touches only billable, not-yet-rebilled expenses in it, so invoicing the EUR group cannot mark the PLN one. [mcp-time-tracker](../time-tracker) bills the hours on the same project; this server bills what the project cost you.

## Free vs Pro

| | Free | Pro |
| --- | --- | --- |
| Logging expenses, mileage and receipts | Unlimited | Unlimited |
| `expense_list` and `expense_summary` | Last 30 days | Full history |
| Projects | 3 | Unlimited |
| Category rules | 5 | Unlimited |
| CSV and JSON export | Up to 200 rows | Unlimited |
| xlsx export | No | Yes |
| `expense_to_invoice` | 20 items at a time, `markup_percent` included | Unlimited items |
| Multi-currency, VAT split, receipt hashing | Yes | Yes |

A limit never writes a partial file and never silently truncates: the export is refused with nothing on disk, and the tool says what to narrow.

Pro is a one-time $19, or $39 for every server in the collection, lifetime.

## Numbers and money

Every amount is an integer number of minor units in the expense's own currency, and every printed amount carries its currency code, for example `EUR 61.50`. How many minor units make one unit comes from an ISO 4217 table, not a guess: 2 for most currencies, 0 for JPY, KRW, VND, CLP, ISK and the rest of the zero-decimal list, 3 for BHD, IQD, JOD, KWD, LYD, OMR and TND, 4 for CLF and UYW. So `KWD 1.234` is 1234 minor units, not 123. The same table is used by [mcp-invoice](../invoice), because the two servers exchange amounts. HUF is 2 decimals here: ISO 4217 gives it two minor digits even though it is usually quoted without them.

The amount you record is the gross on the receipt. `vat_rate` splits it by rounding the VAT, not the net: `vat = round(gross * rate / (100 + rate))`, `net = gross - vat`, so net plus VAT is always exactly the gross and a half-cent of VAT rounds up instead of disappearing (EUR 0.03 at 23% is net 0.02 plus VAT 0.01). Summaries sum already-rounded per-expense values inside one currency; currencies are never added together and never converted. Mileage money is `round(distance * rate)` in the rate's currency. Dates are ISO `YYYY-MM-DD`.

## Privacy

If `data.json` is ever unreadable or not valid JSON, it is not treated as "no expenses yet". The file is moved aside byte-for-byte as `data.json.corrupt-<timestamp>`, a `data.json.corrupt` marker is written, and every tool returns `data file is corrupt; moved to ...; nothing was written` until you restore a good copy and delete the marker, so a truncated file can never be overwritten by an empty database.

All data stays local, in `${XDG_DATA_HOME:-~/.local/share}/mcp-servers/expense-tracker/`. There are no network calls: receipts are hashed on your machine, exports are written on your machine, and license keys are verified offline with a public key compiled into the package.

Built by [theluckystrike](https://github.com/theluckystrike).

## One business profile for the whole suite

Your identity is stored once, at `${XDG_DATA_HOME:-~/.local/share}/mcp-servers/profile/business.json`,
and every server in the suite reads it: the invoice issuer, the docx letterhead, the recurring
issuer, expense-tracker's default VAT rate, time-tracker's and timezone's home zone, and the
resume and contract letterheads. Set it once with `business_set` (invoice or docx) - you never
repeat it anywhere else. An email address is only ever taken from that profile or from an explicit
argument; when none is stored, documents show `[add: email]` and the tool says so rather than
letting anyone improvise an address.

## Frequently asked questions

### Is there a free MCP expense tracker?

Yes. The expense-tracker server at mcp.zovo.one is a free MCP expense tracker: log expenses from Claude or any MCP client with categories, amounts and dates, then list or export them. Free tier, remote hosted endpoint, nothing to install.

### How do I log an expense from Claude?

Connect https://mcp.zovo.one/mcp/expense-tracker (tokenized URL from mcp.zovo.one/mcp/connect) and say: 'Log 42.50 EUR for client lunch, category meals.' The entry is stored locally-first on your machine.

## Use these docs as an MCP server

Any MCP client (Claude, Cursor, Windsurf, VS Code) can read this repository's documentation directly via GitMCP - no install:

- Docs MCP URL: https://gitmcp.io/theluckystrike/mcp-expense-tracker