Log expenses and export clean reports for tax time - your ledger never leaves your machine.
Maintain this server? Claim it
Call this server's tools from your browser. Nothing to install.
Bearer <Pro license key or anonymous token from GET https://mcp.zovo.one/mcp/token>
Requests go through mcptry because browsers can't call most MCP servers directly. Header values are sent to the server for that request only and are never stored or logged.
Tool list from our last check. Connect live to refresh it.
Replace the merchant-to-category rules, or call with no rules to list them. Returns the stored rule list. The rules are applied by expense_add whenever a call gives no category of its own.
The FULL rule list; it replaces the stored one, so include the rules you want to keep. Omit to list the current rules instead
This tool isn't marked read-only, so it may change something on the server or in an account you connected.
Replace the merchant-to-category rules, or call with no rules to list them. Returns the stored rule list. The rules are applied by expense_add whenever a call gives no category of its own.
| Argument | Type | Description |
|---|---|---|
| rules | array | The FULL rule list; it replaces the stored one, so include the rules you want to keep. Omit to list the current rules instead |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"rules": {
"type": "array",
"items": {
"type": "object",
"required": [
"match",
"category"
],
"properties": {
"match": {
"type": "string",
"maxLength": 200,
"description": "Matched against the merchant as a case-insensitive regular expression, and as a plain substring if it is not valid regex. The first matching rule in the list wins"
},
"category": {
"type": "string",
"maxLength": 500,
"description": "Category to apply"
}
},
"additionalProperties": false
},
"maxItems": 500,
"description": "The FULL rule list; it replaces the stored one, so include the rules you want to keep. Omit to list the current rules instead"
}
},
"additionalProperties": false
}Record one expense and return its id, its net/VAT split and its billable flag. The response states every default that was applied, so the caller can see what was assumed rather than having to guess.
| Argument | Type | Description |
|---|---|---|
| vat | number | Alias for vat_rate |
| date | string | ISO date YYYY-MM-DD, default today |
| note | string | |
| amount* | number | Gross amount on the receipt, in major units, e.g. 12.34. It is stored as integer minor units in the expense's own currency, so nothing is lost to floating point. |
| project | string | Project or client this belongs to |
| billable | boolean | Rebillable to the client. Default: true when project is given (a receipt booked to a client project is normally rebilled), false otherwise. Pass it explicitly to override. |
| category | string | Category, e.g. software, travel, office. Omit and the stored category rules are matched against the merchant to fill it in |
| currency | string | ISO code. Defaults to your expense_settings default_currency, else the shared business profile's default_currency, else EUR |
| merchant | string | Who was paid, e.g. Adobe |
| tax_rate | number | Alias for vat_rate |
| vat_rate | number | VAT percent already included in amount; it splits the gross into net and VAT. Omit to use the expense_settings default, or get no split at all when none is set |
Delete one expense by id and report what went. The receipt FILE stays on disk. Deleting a rebilled expense loses the record of what an invoice charged, so correct it with expense_update instead.
| Argument | Type | Description |
|---|---|---|
| id* | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 64
}
},
"additionalProperties": false
}Export the expenses in a date range as csv, xlsx or json and return a download link that is valid for one hour. Nothing partial is ever written: if a limit is hit no file is produced at all.
| Argument | Type | Description |
|---|---|---|
| to* | string | ISO date, inclusive |
| from* | string | ISO date, inclusive |
| path | string | Optional file name for the download, e.g. q3.csv |
| format* | string | |
| project | string | |
| billable | boolean | |
| category | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"to",
"format"
],
"properties": {
"to": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"from": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"path": {
"type": "string",
"maxLength": 4096,
"description": "Optional file name for the download, e.g. q3.csv"
},
"format": {
"enum": [
"csv",
"xlsx",
"json"
],
"type": "string"
},
"project": {
"type": "string",
"maxLength": 500
},
"billable": {
"type": "boolean"
},
"category": {
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}List expenses in a date range with each one's net/VAT split, category, merchant, project and billable flag, plus a total per currency. Free reads the last 30 days and says when your range predates it.
| Argument | Type | Description |
|---|---|---|
| to | string | ISO date, inclusive |
| from | string | ISO date, inclusive |
| project | string | |
| billable | boolean | |
| category | string |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"to": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"from": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"project": {
"type": "string",
"maxLength": 500
},
"billable": {
"type": "boolean"
},
"category": {
"type": "string",
"maxLength": 500
}
},
"additionalProperties": false
}Mark expenses as rebilled once the invoice that carries them actually exists. Pass the expense_ids of one currency group from expense_to_invoice, or that project, date range and currency. Returns what was marked.
| Argument | Type | Description |
|---|---|---|
| to | string | ISO date, inclusive |
| ids | array | Expense ids, as returned per currency by expense_to_invoice. Takes precedence over project/from/to |
| from | string | ISO date, inclusive |
| project | string | Project rebilled, used with from, to and currency |
| currency | string | Required when marking by range: one invoice carries one currency. A range marks only billable, not-yet-rebilled expenses in this one currency, so invoicing the EUR group cannot mark the PLN one |
| invoice_number* | string | Invoice the expenses were billed on. Required: the marker records WHICH invoice carries each expense, and it is stored on every expense marked |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"invoice_number"
],
"properties": {
"to": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"ids": {
"type": "array",
"items": {
"type": "string",
"maxLength": 64
},
"description": "Expense ids, as returned per currency by expense_to_invoice. Takes precedence over project/from/to"
},
"from": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"project": {
"type": "string",
"maxLength": 500,
"description": "Project rebilled, used with from, to and currency"
},
"currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Required when marking by range: one invoice carries one currency. A range marks only billable, not-yet-rebilled expenses in this one currency, so invoicing the EUR group cannot mark the PLN one"
},
"invoice_number": {
"type": "string",
"maxLength": 64,
"description": "Invoice the expenses were billed on. Required: the marker records WHICH invoice carries each expense, and it is stored on every expense marked"
}
},
"additionalProperties": false
}Read or set the defaults expense_add uses when a call does not name them: default_vat_rate and default_currency. Returns the stored defaults. Call with no arguments to read them without changing anything.
| Argument | Type | Description |
|---|---|---|
| default_currency | string | ISO 4217 code to assume when a call gives none, e.g. EUR. Default EUR |
| default_vat_rate | number | VAT percent already included in a receipt, e.g. 23 in Poland, 19 in Germany. Set it once and every later expense gets its net/VAT split without the caller repeating the rate. It applies when the expense is inserted, never retroactively. Pass 0 to clear it |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {
"default_currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "ISO 4217 code to assume when a call gives none, e.g. EUR. Default EUR"
},
"default_vat_rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "VAT percent already included in a receipt, e.g. 23 in Poland, 19 in Germany. Set it once and every later expense gets its net/VAT split without the caller repeating the rate. It applies when the expense is inserted, never retroactively. Pass 0 to clear it"
}
},
"additionalProperties": false
}Totals for a date range grouped by category, project, month or merchant, per currency with gross, net and VAT, never mixed. Receipts only; bank transactions are totalled by bank-statement's statement_summary.
| Argument | Type | Description |
|---|---|---|
| to* | string | ISO date, inclusive |
| from* | string | ISO date, inclusive |
| project | string | |
| billable | boolean | |
| group_by* | string | How to group the totals |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"from",
"to",
"group_by"
],
"properties": {
"to": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"from": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"project": {
"type": "string",
"maxLength": 500
},
"billable": {
"type": "boolean"
},
"group_by": {
"enum": [
"category",
"project",
"month",
"merchant"
],
"type": "string",
"description": "How to group the totals"
}
},
"additionalProperties": false
}Preview the unbilled billable expenses of one project as invoice_create line items (description, quantity, unit_price, tax_rate), grouped per currency. Read-only: nothing is marked rebilled here.
| Argument | Type | Description |
|---|---|---|
| to* | string | ISO date, inclusive |
| from* | string | ISO date, inclusive |
| project* | string | Project or client to rebill |
| fx_rates | object | Rate per source currency, meaning 1 unit of that currency = X units of target_currency, e.g. {"EUR": 1.08, "GBP": 1.27}. You supply the rate; nothing here fetches or guesses one. Omit it when the range holds several currencies and the response names the exact argument to pass |
| markup_percent | number | Percent added to each net amount. Every line's unit_price is the NET amount and its tax_rate is the VAT rate recorded on the expense, so the invoice recomputes the same tax instead of charging it twice and the line total comes back to the receipt gross |
| assume_vat_rate | number | Split expenses that recorded NO VAT rate at this percent, flagged in the description. Only applied when you pass it here. An expense with no rate holds a GROSS amount and is otherwise rebilled as-is with tax_rate 0 plus a warning in its description, so a default tax rate applied on the invoice would tax that receipt a second time. A stored rate of 0 is a real rate (exempt), not a gap. The expense_settings default is never applied retroactively, because that would rewrite the tax meaning of receipts entered before it existed |
Change one expense by id; only the fields you pass move. amount is in MAJOR units. A rebilled expense refuses an amount, currency or vat_rate edit unless unlink_rebill drops the invoice link.
| Argument | Type | Description |
|---|---|---|
| id* | string | Expense id from expense_add or expense_list |
| date | string | |
| note | string | |
| amount | number | |
| project | string | |
| billable | boolean | |
| category | string | |
| currency | string | |
| merchant | string | |
| rebilled | boolean | false clears the rebilled marker and the invoice number, so the expense can be billed again |
| vat_rate | number |
Turn Pro on for this connection with key, an MCPL1.<payload>.<signature> issued at checkout for this server or the bundle. Data under your token stays; a wrong or expired key changes nothing. license_status confirms it.
| Argument | Type | Description |
|---|---|---|
| key* | string | License key from checkout, MCPL1.<payload>.<signature> |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"key"
],
"properties": {
"key": {
"type": "string",
"description": "License key from checkout, MCPL1.<payload>.<signature>"
}
},
"additionalProperties": false
}Report this endpoint's licence state for your token as JSON: the product, the tier free or pro, why it is not Pro, and the checkout URL. Call it to explain a free-tier refusal. No arguments, nothing changes.
No arguments.
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"properties": {}
}Record a business trip as an expense, priced as distance x rate. Give exactly one of km or miles. Returns the saved id with the rate used, where that rate came from and the money, in the rate's own currency.
| Argument | Type | Description |
|---|---|---|
| km | number | Distance in kilometres. Give exactly one of km or miles |
| date | string | ISO date, default today |
| miles | number | Distance in miles. Give exactly one of km or miles |
| region | string | Which built-in table rate to use: PL 1.15 PLN/km, UK 0.45 GBP/mile, US 0.70 USD/mile, EU 0.30 EUR/km. Default US for miles, EU for km. Each is one flat approximate rate per region with no effective dates, no vehicle or engine class and no first-10000-mile band, so it is NOT a tax calculation |
| project | string | Bill the trip to a client or project - use the same name you use in time-tracker and expense_add. Without it the drive is invisible to expense_summary by project and to expense_to_invoice |
| purpose* | string | Why the trip was made, e.g. client meeting in Krakow |
| billable | boolean | Whether the trip is rebilled to the client. Default true, so a mileage claim reaches expense_to_invoice unless you pass false |
| currency |
Not available on the hosted endpoint: it has no filesystem, so there is no receipt file to read or hash. Attach receipts on a local install instead - download expense-tracker.mcpb from https://github.com/theluckystrike/mcp-servers/releases/latest and open it in Claude Desktop - or record the receipt reference in the expense note.
| Argument | Type | Description |
|---|---|---|
| id* | string | Expense id from expense_add or expense_list |
| path* | string | Path to the receipt file. It must already exist; a leading ~ is expanded. The path and its sha256 are stored on the expense |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id",
"path"
],
"properties": {
"id": {
"type": "string",
"maxLength": 64,
"description": "Expense id from expense_add or expense_list"
},
"path": {
"type": "string",
"maxLength": 4096,
"description": "Path to the receipt file. It must already exist; a leading ~ is expanded. The path and its sha256 are stored on the expense"
}
},
"additionalProperties": false
}| receipt_path | string | Absolute path to the receipt file; it is checked and hashed |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"amount"
],
"properties": {
"vat": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Alias for vat_rate"
},
"date": {
"type": "string",
"maxLength": 10,
"description": "ISO date YYYY-MM-DD, default today"
},
"note": {
"type": "string",
"maxLength": 2000
},
"amount": {
"type": "number",
"description": "Gross amount on the receipt, in major units, e.g. 12.34. It is stored as integer minor units in the expense's own currency, so nothing is lost to floating point."
},
"project": {
"type": "string",
"maxLength": 500,
"description": "Project or client this belongs to"
},
"billable": {
"type": "boolean",
"description": "Rebillable to the client. Default: true when project is given (a receipt booked to a client project is normally rebilled), false otherwise. Pass it explicitly to override."
},
"category": {
"type": "string",
"maxLength": 500,
"description": "Category, e.g. software, travel, office. Omit and the stored category rules are matched against the merchant to fill it in"
},
"currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "ISO code. Defaults to your expense_settings default_currency, else the shared business profile's default_currency, else EUR"
},
"merchant": {
"type": "string",
"maxLength": 500,
"description": "Who was paid, e.g. Adobe"
},
"tax_rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Alias for vat_rate"
},
"vat_rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "VAT percent already included in amount; it splits the gross into net and VAT. Omit to use the expense_settings default, or get no split at all when none is set"
},
"receipt_path": {
"type": "string",
"maxLength": 4096,
"description": "Absolute path to the receipt file; it is checked and hashed"
}
},
"additionalProperties": false
}| target_currency | string | Convert every line into this currency and return ONE group, e.g. "USD". Needs fx_rates for each other currency present. Lines are otherwise grouped per currency, because one invoice carries one currency; each converted line carries "[converted from EUR 12.40 at 1.08]" in its description |
| include_rebilled | boolean | Include expenses already marked as rebilled, default false |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"project",
"from",
"to"
],
"properties": {
"to": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"from": {
"type": "string",
"maxLength": 10,
"description": "ISO date, inclusive"
},
"project": {
"type": "string",
"maxLength": 500,
"description": "Project or client to rebill"
},
"fx_rates": {
"type": "object",
"description": "Rate per source currency, meaning 1 unit of that currency = X units of target_currency, e.g. {\"EUR\": 1.08, \"GBP\": 1.27}. You supply the rate; nothing here fetches or guesses one. Omit it when the range holds several currencies and the response names the exact argument to pass",
"additionalProperties": {
"type": "number",
"exclusiveMinimum": 0
}
},
"markup_percent": {
"type": "number",
"maximum": 1000,
"minimum": 0,
"description": "Percent added to each net amount. Every line's unit_price is the NET amount and its tax_rate is the VAT rate recorded on the expense, so the invoice recomputes the same tax instead of charging it twice and the line total comes back to the receipt gross"
},
"assume_vat_rate": {
"type": "number",
"maximum": 100,
"minimum": 0,
"description": "Split expenses that recorded NO VAT rate at this percent, flagged in the description. Only applied when you pass it here. An expense with no rate holds a GROSS amount and is otherwise rebilled as-is with tax_rate 0 plus a warning in its description, so a default tax rate applied on the invoice would tax that receipt a second time. A stored rate of 0 is a real rate (exempt), not a gap. The expense_settings default is never applied retroactively, because that would rewrite the tax meaning of receipts entered before it existed"
},
"target_currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Convert every line into this currency and return ONE group, e.g. \"USD\". Needs fx_rates for each other currency present. Lines are otherwise grouped per currency, because one invoice carries one currency; each converted line carries \"[converted from EUR 12.40 at 1.08]\" in its description"
},
"include_rebilled": {
"type": "boolean",
"description": "Include expenses already marked as rebilled, default false"
}
},
"additionalProperties": false
}| unlink_rebill | boolean | Allow editing amount, currency or vat_rate on a rebilled expense. Clears rebilled_at and rebilled_invoice, because the invoice no longer matches |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"id"
],
"properties": {
"id": {
"type": "string",
"maxLength": 64,
"description": "Expense id from expense_add or expense_list"
},
"date": {
"type": "string",
"maxLength": 10
},
"note": {
"type": "string",
"maxLength": 2000
},
"amount": {
"type": "number"
},
"project": {
"type": "string",
"maxLength": 500
},
"billable": {
"type": "boolean"
},
"category": {
"type": "string",
"maxLength": 500
},
"currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$"
},
"merchant": {
"type": "string",
"maxLength": 500
},
"rebilled": {
"type": "boolean",
"description": "false clears the rebilled marker and the invoice number, so the expense can be billed again"
},
"vat_rate": {
"type": "number",
"maximum": 100,
"minimum": 0
},
"unlink_rebill": {
"type": "boolean",
"description": "Allow editing amount, currency or vat_rate on a rebilled expense. Clears rebilled_at and rebilled_invoice, because the invoice no longer matches"
}
},
"additionalProperties": false
}| string |
| Currency for your own rate. Only accepted together with rate_per_km; a table rate keeps the table currency |
| rate_per_km | number | Your own rate per supplied unit, overriding the table. Pass it whenever you need your exact scheme rather than the approximate table rate |
{
"type": "object",
"$schema": "http://json-schema.org/draft-07/schema#",
"required": [
"purpose"
],
"properties": {
"km": {
"type": "number",
"description": "Distance in kilometres. Give exactly one of km or miles"
},
"date": {
"type": "string",
"description": "ISO date, default today"
},
"miles": {
"type": "number",
"description": "Distance in miles. Give exactly one of km or miles"
},
"region": {
"enum": [
"PL",
"UK",
"US",
"EU"
],
"type": "string",
"description": "Which built-in table rate to use: PL 1.15 PLN/km, UK 0.45 GBP/mile, US 0.70 USD/mile, EU 0.30 EUR/km. Default US for miles, EU for km. Each is one flat approximate rate per region with no effective dates, no vehicle or engine class and no first-10000-mile band, so it is NOT a tax calculation"
},
"project": {
"type": "string",
"maxLength": 500,
"description": "Bill the trip to a client or project - use the same name you use in time-tracker and expense_add. Without it the drive is invisible to expense_summary by project and to expense_to_invoice"
},
"purpose": {
"type": "string",
"maxLength": 2000,
"description": "Why the trip was made, e.g. client meeting in Krakow"
},
"billable": {
"type": "boolean",
"description": "Whether the trip is rebilled to the client. Default true, so a mileage claim reaches expense_to_invoice unless you pass false"
},
"currency": {
"type": "string",
"pattern": "^[A-Za-z]{3}$",
"description": "Currency for your own rate. Only accepted together with rate_per_km; a table rate keeps the table currency"
},
"rate_per_km": {
"type": "number",
"minimum": 0,
"description": "Your own rate per supplied unit, overriding the table. Pass it whenever you need your exact scheme rather than the approximate table rate"
}
},
"additionalProperties": false
}