<p align="center">
  <img src="icon.png" width="80" alt="TripLedger" />
</p>

# TripLedger MCP server

**A remote MCP server for your personal travel history.** Connect Claude, ChatGPT, Cursor or any
MCP client to [TripLedger](https://tripledger.app) and keep a durable ledger of where you've been:
journeys, stays and travel expenses, with tax-residency day counts and Schengen 90/180 status
computed from your records.

- **Endpoint:** `https://my.tripledger.app/mcp` (Streamable HTTP)
- **Auth:** OAuth 2.1 (browser consent) or a `tl_` API key
- **Docs:** [docs.tripledger.app](https://docs.tripledger.app/connect/credentials/)

This repository contains connection instructions and configuration only. TripLedger is a hosted
service; nothing here runs locally.

## What you can ask

- "Log my flight from this booking email: LHR → BCN on 14 March, back on the 21st."
- "How many Schengen days do I have left if I travel to Lisbon on 2 June?"
- "How many days have I spent in Spain this year, and in the last 365 days?"
- "Where am I according to my travel ledger?"
- "Find gaps in my 2025 travel history before I send it to my accountant."

## Connect

### Claude.ai / Claude Desktop (OAuth)

1. **Settings → Connectors → Add custom connector**
2. Paste `https://my.tripledger.app/mcp`
3. Log in to TripLedger and approve. Each grant binds one ledger.

### Claude Code (API key)

Create a key in TripLedger under **Settings → API keys** (shown once), then:

```bash
claude mcp add --transport http tripledger https://my.tripledger.app/mcp \
  --header "Authorization: Bearer tl_YOUR_KEY"
```

### Other MCP clients

Clients that support remote OAuth: [`configs/mcp-oauth.json`](configs/mcp-oauth.json).
Clients that need a header: [`configs/mcp-api-key.json`](configs/mcp-api-key.json).

Treat API keys like passwords. Revoke keys and OAuth grants anytime in TripLedger
**Settings → API keys / Connected apps**.

## Tools

**Read**

| Tool | What it does |
|---|---|
| `get_profile` | Connected ledger and credential scope |
| `get_tripledger_guide` | Operating guide for agents |
| `get_journey_review` | Booked journeys that are now overdue for confirmation |
| `search_locations` | Cities by name or airport code |
| `list_people` | Travelers in the ledger |
| `list_journeys` / `get_journey` | Journeys (the presence record) |
| `list_stays` / `get_stay` | Accommodation |
| `list_expenses` | Costs attached to journeys and stays |
| `list_loyalty_programs` / `list_loyalty_accounts` | Loyalty programs and accounts (numbers masked) |
| `get_travel_summary` | Days per country |
| `get_residency_status` | Days against configured tax-residency thresholds |
| `check_schengen_status` | Rolling Schengen 90/180 status |
| `get_current_country` | Current country from recorded journeys |
| `detect_journey_gaps` | Missing movements that make counts uncertain |
| `get_methodology` | How every count is calculated |

**Write**

`log_journey`, `update_journey`, `delete_journey`, `log_stay`, `update_stay`, `delete_stay`,
`log_expense`, `update_expense`, `delete_expense`, `create_loyalty_account`,
`update_loyalty_account`, `delete_loyalty_account`, `set_journey_preferences`.

Live tool schemas from the server are authoritative.

## Access and pricing

- 14-day trial, then a one-time **$97 lifetime** license per ledger. No subscription.
- After a trial ends the ledger is read-only: reads, calculations and MCP read tools keep working.
- 5,000 MCP requests per ledger per day.
- Writes need an owner or editor role; viewers get read tools.

## Agent plugin

[`plugin/`](plugin) is an [Agent Plugins](https://agent-plugins.org) package: the MCP server plus a
`managing-tripledger` workflow skill that teaches agents to capture travel from evidence, never
invent records, and confirm before deleting.

## Not

TripLedger is a ledger, not flight or hotel search, a booking service, or live location tracking.
Results depend on the travel you record. They are informational, not tax or legal advice, and not
a guarantee of admission at any border.

## Links

[Website](https://tripledger.app) · [Docs](https://docs.tripledger.app) ·
[Schengen tracking](https://tripledger.app/schengen-tracking/) ·
[Tax-residency day counter](https://tripledger.app/tax-residency/) ·
[Privacy](https://tripledger.app/privacy/) · [Terms](https://tripledger.app/terms/) ·
[support@tripledger.app](mailto:support@tripledger.app)

Made by [Pianosa Labs](https://pianosa.io).