Timeline MCP

An MCP server that lets an AI assistant answer questions about your Google Timeline: "Where was I on 3 March?", "When was I at the bakery in Meppel?", "How far did I cycle last week?".

It reads a Timeline export, indexes it into SQLite, and serves it over MCP (stdio or streamable HTTP). Your data stays on your machine, except for the optional place lookups described below.

Export your Timeline (Android)

Google Timeline data is stored on your phone, not in your Google account, so you export it from the device:

1. Open the Settings app → Location → Location services → Timeline. (Alternatively: Google Maps → your profile picture → Your Timeline → ⋮ → Location & privacy settings.)

2. Tap Export Timeline data and choose where to save the file.

3. Copy the resulting JSON file (e.g. Timeline.json, or Tijdlijn.json on a Dutch phone) to the machine that runs the server.

Menu names can differ slightly per Android version and manufacturer.

This server supports the new on-device export format: one JSON file with a top-level semanticSegments array. The older Google Takeout export (Records.json, Semantic Location History/) is not supported.

Related MCP server: Google Maps MCP Server

Getting started

Requires Node.js 22+. npx downloads this repository, builds it, and runs it over stdio, so there is nothing to clone or keep running:

claude mcp add timeline \
  -e TIMELINE_JSON_PATH=/absolute/path/to/Timeline.json \
  -e TIMELINE_DB_PATH=/absolute/path/to/timeline.db \
  -- npx -y github:idserda/timeline-mcp

• Windows: use cmd /c npx … as the command.

• Versions: the first start is slower while npm builds the package; it is cached afterwards. Pin a version with github:idserda/timeline-mcp#v0.1.0, or run npx clear-npx-cache to pick up the latest master.

• Updates to your export: the index is rebuilt automatically on the next start when the export file has changed.

Run claude mcp list to check that the server connects.

Running as an HTTP server (Docker)

To run one long-lived server that several clients can share:

docker build -t timeline-mcp .

docker run -d --name timeline-mcp --restart unless-stopped \
  -p 3000:3000 \
  --env-file timeline.env \
  -v "$PWD/Timeline.json:/data/Timeline.json:ro" \
  -v "$PWD/.timeline-data:/data/state" \
  timeline-mcp

claude mcp add --transport http timeline http://localhost:3000/mcp

timeline.env holds the configuration as NAME=value lines, at least TIMELINE_JSON_PATH=/data/Timeline.json and TIMELINE_DB_PATH=/data/state/timeline.db. The .timeline-data/ folder keeps the database, so lookups survive restarts. /health returns ok.

Security: the HTTP server has no authentication and is reachable from your network, so only run it on trusted networks. To keep it local to the machine, publish the port as -p 127.0.0.1:3000:3000.

Configuration

Tools

Resources: timeline://stats, timeline://day/{date}, and timeline://segment/{id}.

Place names

The export only contains coordinates and Google place IDs (like ChIJN1t_tDeuEmsRUsoyG83frY4), not names. Run the enrich_places tool once after the first start, and again after importing a new export, to look them up:

• OpenStreetMap (free, always on): turns coordinates into an address, city, and country. Limited to 1 request per second, so the first run can take a while.

• Google Places (optional, set TIMELINE_GOOGLE_PLACES_API_KEY): turns place IDs into real names like "Albert Heijn", plus a category ("Supermarket"), address, and Google Maps link. The key needs Places API (New) enabled. Each lookup is billed as a Place Details (Pro) request.

Results are cached in the database, so each place is looked up only once. If Google rate-limits you, enrich_places stops, keeps what it has, and reports how many places are remaining. Run it again later to continue.

A visit is labelled using the first available of: your alias, Home/Work from Google, the Google place name, then the OpenStreetMap address.

Searching places

search_places and when_was_i_at_place take a free-text query. A place matches when every word appears in its name, address, city, or category. Partial words count, capitals and accents don't matter, and small words like in, the, and de are ignored. For example, Bakker in Meppel finds "Bakkerij Jansen, Hoofdstraat 1, Meppel" but not bakeries in other towns, and cafe finds "Café de Kroon".

Names and categories come from enrich_places, so run that first. With TIMELINE_GOOGLE_PLACES_LANGUAGE=nl, Dutch words like bakker and supermarkt work as well as English ones.

Aliases

Optionally give places your own names with a JSON file set in TIMELINE_ALIASES_PATH:

{
  "placeIds": {
    "ChIJN1t_tDeuEmsRUsoyG83frY4": "Ten Forward"
  },
  "semanticTypes": {
    "WORK": "The Bridge"
  }
}

Development

npm install
npm test
npm run build
TIMELINE_JSON_PATH=/path/to/Timeline.json TIMELINE_DB_PATH=/path/to/timeline.db npm run dev

License

MIT