Garage MCP

garage-mcp is a local, single-user Model Context Protocol server for keeping the history of several personal vehicles. It stores mileage, maintenance and parts, standalone expenses, local document references, reminders, and cost summaries in SQLite.

The application has no web interface, HTTP business API, authentication, cloud storage, telemetry, LLM call, OBD integration, or notification service. Its only application entry point is MCP over stdio.

Requirements

• Node.js 24 LTS
• pnpm 10 or newer
• a local MCP client that supports stdio

The project pins its package manager and all direct dependency versions. Node 24 is enforced through engines and .node-version.

Install and run

git clone https://github.com/fsioni/my-garage-map.git
cd my-garage-map
corepack enable
pnpm install --frozen-lockfile
cp .env.example .env
pnpm db:migrate
pnpm build
pnpm start

For development:

pnpm dev

The server reserves stdout for JSON-RPC. Structured operational logs go to stderr only. The database directory and schema are created at startup, so running db:migrate separately is explicit but not required.

The package is marked private to prevent accidental publication to npm. This does not affect cloning, building, or using the open source repository.

Configuration

Variable	Default	Meaning
GARAGE_DB_PATH	./data/garage.sqlite	SQLite file, or :memory: in tests
GARAGE_LOG_LEVEL	info	debug, info, warn, or error
GARAGE_DOCUMENT_ROOT	unset	Optional root allowed for document paths

When GARAGE_DOCUMENT_ROOT is set, attached paths are resolved and rejected if they escape that root, including .. traversal. Files are not copied and do not need to exist in V1.

MCP client configuration

Build the project, then add an entry like this to a local MCP client's configuration. Replace the path with the absolute checkout path.

{
  "mcpServers": {
    "garage": {
      "command": "node",
      "args": ["/absolute/path/to/my-garage-map/dist/main.js"],
      "env": {
        "GARAGE_DB_PATH": "/absolute/path/to/my-garage-map/data/garage.sqlite",
        "GARAGE_DOCUMENT_ROOT": "/absolute/path/to/vehicle-documents"
      }
    }
  }
}

Restart the client after changing its MCP configuration. The Node executable selected by the client must be Node 24.

Tools

All list tools have stable sorting and accept limit (default 50, maximum 200) and offset. Input objects are strict and reject unknown fields.

Area	Tools
Vehicles	create_vehicle, list_vehicles, get_vehicle, update_vehicle
Mileage	record_mileage, get_current_mileage, list_mileage_records
Maintenance	add_maintenance, get_maintenance, list_maintenance, update_maintenance, delete_maintenance
Expenses	add_expense, list_expenses, update_expense, delete_expense
Reminders	add_reminder, list_due_reminders, list_reminders, complete_reminder
Documents	attach_document, list_documents, remove_document
Summary	get_vehicle_summary

Monetary inputs use euro strings such as "12", "12.5", or "12.50". Values such as "12.345", "-3", and "12,50" are rejected. Values are converted to integer cents without using binary floating-point arithmetic.

Example requests in natural language:

• “Add my 2013 Peugeot 2008 at 185,146 km.”
• “Record 186,020 km today for the Peugeot.”
• “Add an oil service at 186,020 km: €45 labor and one €62.50 oil kit.”
• “Remind me to inspect the brakes at 190,000 km.”
• “Attach /Users/me/Documents/car/oil-invoice.pdf to the last service.”
• “Show the Peugeot's cost summary.”

Resources

Resources are read-only UTF-8 JSON:

• garage://vehicles
• garage://vehicles/{vehicleId}
• garage://vehicles/{vehicleId}/maintenance
• garage://vehicles/{vehicleId}/expenses
• garage://vehicles/{vehicleId}/reminders
• garage://vehicles/{vehicleId}/summary

Data model and behavior

• Vehicle owns mileage, maintenance, expenses, reminders, and documents.
• Maintenance owns parts. Part and maintenance totals are calculated from integer cents.
• Adding maintenance above current mileage atomically adds a mileage record.
• Current mileage is the record newest by recorded date and then creation timestamp.
• Equal mileage is allowed when its date or source differs. A fully identical record is rejected by a database uniqueness constraint.
• A reminder is due in the 30 days or 1,000 km before either threshold, overdue after a threshold, upcoming otherwise, and completed when completed.
• Completing a recurring reminder preserves it and atomically creates a successor. Its date is advanced from the previous due date by the recurrence in calendar months (end-of-month clamped); mileage is advanced from the previous due mileage.
• Maintenance costs never create an expense row. Summaries report maintenance, standalone expenses, their combined total, and category breakdown separately to prevent double counting.
• Deleting maintenance or an expense explicitly detaches its document records. It never deletes files or relies on an implicit cascading delete.

See ARCHITECTURE.md and docs/adr for design details.

Migrations and seed

Versioned SQL migrations live in drizzle/.

pnpm db:generate
pnpm db:migrate

The optional seed creates a Peugeot 2008 1.6 e-HDi Allure (2013), an initial 185,146 km, purchase and transport expense placeholders, and a brake reminder:

pnpm seed

The seed refuses to run if the target database already contains a vehicle.

Tests and quality

pnpm test
pnpm test:unit
pnpm test:integration
pnpm test:contract
pnpm test:coverage
pnpm check

The suite contains 370 tests. Unit and property tests cover domain rules, exact money handling, date and path validation, recurrence boundaries, configuration, both clocks, document storage, and the full in-memory repository. Integration tests use real SQLite :memory: databases and migrations to verify constraints, indexes, foreign keys, stable ordering, pagination, transactions, rollback, all repositories, summaries, and the stdio process lifecycle. Contract tests connect an official SDK Client to the server through an in-memory transport and verify every tool surface, strict schemas, validation boundaries, safe business errors, resources, optional-field semantics, pagination, recurrence, and document linking.

Coverage gates instrument all application logic (domain, configuration, repositories, filesystem and clock adapters, presenters, and MCP server): lines, statements, and functions must be at least 90%, and branches at least 85%. Declarative database schema and executable entry-point scripts are covered by integration behavior instead of source instrumentation.

pnpm check runs format checking, lint, strict TypeScript, coverage tests, and the production build. CI runs that command on every push and pull request.

Security and privacy

Garage data may contain sensitive personal information. The database, .env files, generated build output, coverage output, logs, and common SQLite sidecar files are ignored by Git. Nevertheless, review every staged change before pushing and use synthetic data in issues and tests.

This server is intended for a trusted local user. It does not provide authentication or sandbox the MCP client. Configure GARAGE_DOCUMENT_ROOT, protect the checkout and data directory with operating-system permissions, and do not expose the stdio process through an untrusted network bridge.

Report vulnerabilities privately according to SECURITY.md.

Backup

Stop the MCP client first so SQLite has no active writer, then copy the database file:

cp ./data/garage.sqlite ./backups/garage-$(date +%Y-%m-%d).sqlite

If copying while the server is running is unavoidable, use SQLite's online backup command instead of copying only the main file:

sqlite3 ./data/garage.sqlite ".backup './backups/garage.sqlite'"

Restore only while the server is stopped, and keep an additional copy of the replaced file.

V1 limits

• single local user and one process writing the database;
• no vehicle deletion tool;
• no document copying, file-existence check, or file deletion;
• offset pagination rather than cursor pagination;
• monetary tool inputs are denominated in euros; stored vehicle currency defaults to EUR;
• no automatic notifications or background scheduler.

Contributing

Contributions are welcome. Read CONTRIBUTING.md, the Code of Conduct, and SUPPORT.md before opening an issue or pull request. User-visible changes should be recorded in CHANGELOG.md.

License

Garage MCP is available under the MIT License.