io.github.theluckystrike/mileage-logbook

Official9 toolsLive

by theluckystrike · JavaScript

A mileage logbook for deductible driving: trips, effective-dated rates, summaries, CSV export.

A mileage logbook for deductible driving, supporting trip tracking, effective-dated rates, summaries, and CSV export. It provides functionality to record driving trips and compute or apply rate information over time, then produce summary outputs suitable for export.

🛠️ Key Features

Trips logging
Effective-dated rates
Summaries
CSV export

🚀 Use Cases

Tracking deductible driving trips
Applying mileage rates that change over time
Generating summarized mileage results
Exporting data to CSV for further use

⚡ Developer Benefits

Structured outputs via summaries
Interoperable CSV export for downstream workflows

⚠️ Limitations

Limited to mileage logbook functionality as described (trips, effective-dated rates, summaries, CSV export)

Topics

claudecursorinvoicemcpmcp-servermodel-context-protocolspreadsheetaccountingai-toolsbookkeepingclaude-desktopfreelanceinvoicinglocal-firstmcp-serverspdfself-hostedtime-trackingvatproductivity

Captured live from the server via tools/list.

trip_add

Log one drive in the mileage log: the date, where from and to, the distance in miles or km, the purpose, and the category (business, medical, moving, charitable, personal). Returns its TR-YYYY-NNNN id. Free tier: 20 trips per calendar month, counted on the month of the trip date.

Parameters9

date	string	required	The day the trip was driven, YYYY-MM-DD. A future date is refused: the trip cannot have been driven yet
from	string	required	Where the trip started, e.g. Home office, 14 Nowa Street
to	string	required	Where it ended, e.g. Client site, 2 Mill Lane
distance	number	required	How far, to the thousandth of the unit, e.g. 12.5
unit	string	required	miles or km; spellings like mi and kilometre are accepted
purpose	string	required	Why the trip was made, e.g. Site visit for the Kowalski refit
category	string	required	One of: business, medical, moving, charitable, personal. Personal trips are kept for the record and priced only if a rate exists
jurisdiction	string	optional	Which rate set prices this trip, when more than one jurisdiction has a rate for its category. Omit when only one does
note	string	optional

Raw schema

{
  "type": "object",
  "properties": {
    "date": {
      "type": "string",
      "maxLength": 10,
      "description": "The day the trip was driven, YYYY-MM-DD. A future date is refused: the trip cannot have been driven yet"
    },
    "from": {
      "type": "string",
      "maxLength": 200,
      "description": "Where the trip started, e.g. Home office, 14 Nowa Street"
    },
    "to": {
      "type": "string",
      "maxLength": 200,
      "description": "Where it ended, e.g. Client site, 2 Mill Lane"
    },
    "distance": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "How far, to the thousandth of the unit, e.g. 12.5"
    },
    "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "miles or km; spellings like mi and kilometre are accepted"
    },
    "purpose": {
      "type": "string",
      "maxLength": 200,
      "description": "Why the trip was made, e.g. Site visit for the Kowalski refit"
    },
    "category": {
      "type": "string",
      "maxLength": 20,
      "description": "One of: business, medical, moving, charitable, personal. Personal trips are kept for the record and priced only if a rate exists"
    },
    "jurisdiction": {
      "type": "string",
      "maxLength": 100,
      "description": "Which rate set prices this trip, when more than one jurisdiction has a rate for its category. Omit when only one does"
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    }
  },
  "required": [
    "date",
    "from",
    "to",
    "distance",
    "unit",
    "purpose",
    "category"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

trip_list

List trips in the mileage log, oldest first: date, from, to, distance, category, and the amount each earns under the rate in force on its day (or the plain reason it is unpriced). Filter by date range and category. Reads only.

Parameters3

from_date	string	optional	Only trips dated on or after this, YYYY-MM-DD
to_date	string	optional	Only trips dated on or before this, YYYY-MM-DD
category	string	optional	Only trips of this category: business, medical, moving, charitable, personal

Raw schema

{
  "type": "object",
  "properties": {
    "from_date": {
      "type": "string",
      "maxLength": 10,
      "description": "Only trips dated on or after this, YYYY-MM-DD"
    },
    "to_date": {
      "type": "string",
      "maxLength": 10,
      "description": "Only trips dated on or before this, YYYY-MM-DD"
    },
    "category": {
      "type": "string",
      "maxLength": 20,
      "description": "Only trips of this category: business, medical, moving, charitable, personal"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

trip_remove

Remove one trip from the mileage log by its exact TR-YYYY-NNNN id, for entries made by mistake. The id is not reissued: a gap in the TR series is the record that a trip was removed.

Parameters1

string

required

The exact trip id, e.g. TR-2026-0003

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "maxLength": 20,
      "description": "The exact trip id, e.g. TR-2026-0003"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

rate_set

Set what one mile or km is worth for one category in one jurisdiction from a date forward: the jurisdiction label, the category, the rate per unit, the currency, and the date it takes effect. Rates form a series per jurisdiction and category, and each trip earns the rate in force on the day it was driven. No rate ships with this server; the figures are yours to verify. Free tier: one rate per jurisdiction and category; the year-over-year series is Pro.

Parameters6

jurisdiction	string	required	A label for the rate set, e.g. US federal or Canada federal. It is a label, not legal advice
category	string	required	Which category this prices: business, medical, moving, charitable, personal
rate	number	required	The rate per unit in currency units, to the thousandth, e.g. 0.70 for 70 cents a mile
unit	string	required	The distance unit the rate prices
currency	string	required	ISO code the rate is in
effective_from	string	required	The date the rate starts to apply, YYYY-MM-DD. May be in the future: authorities announce next year's rate ahead of time

Raw schema

{
  "type": "object",
  "properties": {
    "jurisdiction": {
      "type": "string",
      "maxLength": 100,
      "description": "A label for the rate set, e.g. US federal or Canada federal. It is a label, not legal advice"
    },
    "category": {
      "type": "string",
      "maxLength": 20,
      "description": "Which category this prices: business, medical, moving, charitable, personal"
    },
    "rate": {
      "type": "number",
      "exclusiveMinimum": 0,
      "description": "The rate per unit in currency units, to the thousandth, e.g. 0.70 for 70 cents a mile"
    },
    "unit": {
      "type": "string",
      "maxLength": 20,
      "description": "The distance unit the rate prices"
    },
    "currency": {
      "type": "string",
      "pattern": "^[A-Za-z]{3}$",
      "description": "ISO code the rate is in"
    },
    "effective_from": {
      "type": "string",
      "maxLength": 10,
      "description": "The date the rate starts to apply, YYYY-MM-DD. May be in the future: authorities announce next year's rate ahead of time"
    }
  },
  "required": [
    "jurisdiction",
    "category",
    "rate",
    "unit",
    "currency",
    "effective_from"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

rate_list

List every mileage rate on file, grouped by jurisdiction and category with the effective-from dates in order: the series each trip is priced from. Reads only.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mileage_summary

The deductible mileage for a date range, per category: trips, distance kept per unit, the rate each trip earned (the one in force on its day), and the deductible amount, totalled per currency. Trips with no applicable rate are listed with the reason, not silently dropped. Defaults to the current calendar year. Never metered.

Parameters3

from_date	string	optional	Start of the range, YYYY-MM-DD. Default January 1 of the current year
to_date	string	optional	End of the range, YYYY-MM-DD. Default December 31 of the current year
category	string	optional	Only this category: business, medical, moving, charitable, personal

Raw schema

{
  "type": "object",
  "properties": {
    "from_date": {
      "type": "string",
      "maxLength": 10,
      "description": "Start of the range, YYYY-MM-DD. Default January 1 of the current year"
    },
    "to_date": {
      "type": "string",
      "maxLength": 10,
      "description": "End of the range, YYYY-MM-DD. Default December 31 of the current year"
    },
    "category": {
      "type": "string",
      "maxLength": 20,
      "description": "Only this category: business, medical, moving, charitable, personal"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

mileage_export

The mileage log as CSV, one row per trip, oldest first: date, from, to, distance, unit, category, the rate applied (the one in force on the trip's day), the currency and the amount, plus purpose, jurisdiction, effective_from and id. The amount column is a bare number a spreadsheet reads. Refuses while any non-personal trip in the window is unpriced, so an accountant never receives a log with silent gaps. Pro.

Parameters2

from_date	string	optional	Start of the range, YYYY-MM-DD. Default January 1 of the current year
to_date	string	optional	End of the range, YYYY-MM-DD. Default December 31 of the current year

Raw schema

{
  "type": "object",
  "properties": {
    "from_date": {
      "type": "string",
      "maxLength": 10,
      "description": "Start of the range, YYYY-MM-DD. Default January 1 of the current year"
    },
    "to_date": {
      "type": "string",
      "maxLength": 10,
      "description": "End of the range, YYYY-MM-DD. Default December 31 of the current year"
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

license_status

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.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "$schema": "http://json-schema.org/draft-07/schema#"
}

license_activate

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.

Parameters1

key

string

required

License key from checkout, MCPL1.<payload>.<signature>

Raw schema

{
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "description": "License key from checkout, MCPL1.<payload>.<signature>"
    }
  },
  "required": [
    "key"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

servers/mileage-log/README.md6 KBView on GitHub

mcp-mileage-log

In the official MCP Registry (io.github.theluckystrike/mileage-log). An mcp mileage tracker that keeps the mileage log freelancers need at tax time, the moment the drive happens instead of reconstructed from memory in April. Log each trip with the date, from and to, the distance in miles or km, the purpose and the category (business, medical, moving, charitable, personal); set the rates that apply to you as an effective-dated series per jurisdiction and category; and the summary prices every trip at the rate in force on the day it was driven, per category and per currency. When the log is right, one call exports it as CSV to hand to your accountant. Everything stays on this machine; there is no account and no network call.

Built by theluckystrike.

npm publish for @theluckystrike/mcp-mileage-log is pending, so npx -y @theluckystrike/mcp-mileage-log returns 404 today. Until then, a clone+build is the working path.

Install

Claude Desktop

macOS ~/Library/Application Support/Claude/claude_desktop_config.json, Windows %APPDATA%\Claude\claude_desktop_config.json:

json

{
  "mcpServers": {
    "mileage-log": {
      "command": "npx",
      "args": ["-y", "@theluckystrike/mcp-mileage-log"]
    }
  }
}

Claude Code

claude mcp add mileage-log -- npx -y @theluckystrike/mcp-mileage-log

Cursor

~/.cursor/mcp.json (global) or .cursor/mcp.json (project), same entry as Claude Desktop.

Tools

tool	what it does
`trip_add`	Log one trip: date, from, to, distance in miles or km, purpose, category. Returns `TR-YYYY-NNNN`
`trip_list`	List trips oldest first, with the rate and amount each earns; filter by date range and category
`trip_remove`	Remove a trip by its exact id, for entries made by mistake. The id is not reissued
`rate_set`	Set what one mile or km is worth for one category in one jurisdiction from a date forward. A series, not one global number
`rate_list`	Every rate on file, grouped by jurisdiction and category with effective dates in order
`mileage_summary`	A date range (default the current year): per-category distance, the rate each trip earned, and the deductible amount, per currency
`mileage_export`	The log as CSV for an accountant: date, from, to, distance, category, rate, amount. Pro
`license_status` / `license_activate`	Free or Pro, and the key

Rates are a series, and none ship with the server

Tax authorities change their mileage rates, usually every year, so this server never holds one global rate: rate_set adds a rate for a jurisdiction, a category and a unit from an effective date, and each trip earns the rate in force on its own day. No rates ship with this server, and the example below is an EXAMPLE, not a statement of current law. Verify the figures that apply to you before you file.

An example rate set (illustrative only):

text

rate_set jurisdiction:"US federal (EXAMPLE)" category:business    rate:0.70  unit:miles currency:USD effective_from:2026-01-01
rate_set jurisdiction:"US federal (EXAMPLE)" category:business    rate:0.655 unit:miles currency:USD effective_from:2025-01-01
rate_set jurisdiction:"US federal (EXAMPLE)" category:medical     rate:0.21  unit:miles currency:USD effective_from:2026-01-01
rate_set jurisdiction:"US federal (EXAMPLE)" category:charitable  rate:0.14  unit:miles currency:USD effective_from:2026-01-01

A 2025 trip then prices at 0.655 and a 2026 trip at 0.70, automatically. If your trips are in km and your rate is per mile (or the other way around), the distance is converted with the exact factor (1 mile = 1.609344 km) before pricing.

Free vs Pro

	Free	Pro
Trips per calendar month	20	Unlimited
Trip list and mileage summary	Yes	Yes
Rates per jurisdiction and category	1 (overwrite stays free)	Unlimited series
CSV export for the accountant	No	Yes

The monthly cap is counted on the month of the trip date, so reconstructing last year's log at tax time does not consume this month's allowance. The log itself is never metered: reading, listing and summarizing stay free for good.

Get Pro: https://mcp.zovo.one/buy/mileage-log, $19 one-time for this server, or $39 for the bundle.

Money and rounding

A trip's deductible amount is its distance times the effective rate, rounded half-up to the cent per trip, and every total is the sum of those rounded per-trip amounts: a total can never drift from the lines it is made of, and the CSV export reconciles line by line with the summary. The arithmetic is integer-only (distances as thousandths of a unit, rates as thousandths of a currency unit), so 12.5 miles at 0.70 a mile is exactly 875 cents, never 874.99999. Miles and km are kept apart and never added together; amounts are kept per currency and never mixed. When a trip's unit differs from the rate's, the distance is converted first (1 mile = 1.609344 km exactly) and rounded half-up to the thousandth of the rate's unit, then priced.

Privacy

All data stays local, in ${XDG_DATA_HOME:-~/.local/share}/mcp-servers/mileage-log/. Three files: trips.json, rates.json, counter.json. Nothing is sent anywhere, there is no account, no API key and no network call in this server at all. License keys are verified offline. Nothing this server computes is tax advice; the rates you enter are your own figures to verify.

Built by theluckystrike. https://github.com/theluckystrike

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-mileage-log

Install

Tools (9)

trip_addtrip_listtrip_removerate_setrate_listmileage_summarymileage_exportlicense_status

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.zovo.one/mcp/mileage-logbook

Configuration

Environment variables

MCP_LICENSE_KEYsecret

Optional Pro license key (MCPL1....). Verified offline.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "mileage-logbook": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.zovo.one/mcp/mileage-logbook"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

trip_add

trip_list

trip_remove

rate_set

rate_list

mileage_summary

mileage_export

license_status

license_activate

mcp-mileage-log

Install

Claude Desktop

Claude Code

Cursor

Tools

Rates are a series, and none ship with the server

Free vs Pro

Money and rounding

Privacy

Use these docs as an MCP server

Install

Remote endpoint

Configuration

Related servers