OpenJetLag MCP

Turn your personal AI agent into a jet lag coach.

OpenJetLag is an open-source Model Context Protocol server. Connect it to an agent such as Meta Muse, ChatGPT, Claude or any MCP client, tell the agent about your flight, and it gets a science-based, day-by-day plan: when to seek or avoid light, when to sleep, when to stop caffeine, when not to nap, and optional melatonin timing, from the days before you leave until your body clock matches the destination. Every item has an exact timestamp, so the agent can remind you proactively.

中文说明

You ──▶ your agent (Muse, ChatGPT, Claude, …) ──MCP──▶ OpenJetLag server ──▶ @openjetlag/core engine
         conversation, memory, reminders            stateless, stores nothing       pure computation

Your agent does the talking, remembering and reminding. This project only supplies the expertise: a deterministic planning engine and guidance on how to use it.

Connect it to your agent

You need the server's URL. Until the public endpoint is announced here, deploy your own (free on Cloudflare) and use https://<your-worker>.workers.dev/mcp.

Then just say something like "I fly from Shanghai to London on Dec 18, 10:00, landing 15:00. Help me with jet lag."

Agent Skill (optional, recommended). skills/openjetlag/SKILL.md is a playbook in the open Agent Skills format that teaches an agent how to coach: what to ask, how to present the plan, how to schedule reminders and check in. Agents that support skills can install that folder. The server also sends a condensed version as MCP instructions, so agents without skill support behave well too.

Related MCP server: tripkit

Tools

All tools are read-only and idempotent.

Inputs to plan_jetlag_trip: origin and destination IANA time zones, local departure and arrival date and time, usual bedtime and wake time; optional pre_trip_days (default 3), melatonin (default true, timing only), strategy (auto), language (en or zh).

How the plan works

The engine (packages/core) estimates your body clock from your usual wake time and moves it toward the destination at a realistic pace: about 1 hour per day when shifting earlier (usually eastward) and 1.5 hours per day when shifting later. For large eastward trips it compares both directions and picks the faster one. Light windows are timed to your body clock and only placed while you are awake; sleep moves toward local time after departure; sleep that overlaps the flight becomes in-flight sleep; daylight saving is applied for the actual trip dates. See the core README for the model and options.

This is educational guidance, not medical advice. Plans never include a melatonin dose, and every response carries safety notes for the agent to show.

Privacy

• Stateless: each request is computed and forgotten. No database, no accounts, no cookies.

• No content logging: the server does not log tool arguments (flight details, sleep times) or results.

• Your agent's provider handles your conversation under its own privacy policy. This server only sees the trip details your agent sends in a tool call.

Self-hosting

Cloudflare Workers (free plan: 100,000 requests/day):

git clone https://github.com/willbuildtolast/openjetlag-mcp && cd openjetlag-mcp
npm install
npx wrangler login
npm run deploy        # prints https://openjetlag-mcp.<you>.workers.dev

Your MCP URL is that address plus /mcp. GET /health returns the version.

To deploy automatically on every push to main (after tests pass), add CLOUDFLARE_API_TOKEN (template "Edit Cloudflare Workers") and CLOUDFLARE_ACCOUNT_ID as repository secrets; see .github/workflows/deploy.yml. A step-by-step guide in Chinese is in docs/DEPLOY.zh-CN.md.

Node.js (any VPS or container, Node 20+):

npm install && npm run build
PORT=8787 HOST=0.0.0.0 npm start -w @openjetlag/mcp-server

Put it behind HTTPS before connecting a cloud-hosted agent. To try it locally, run npm run dev and point the MCP Inspector at http://127.0.0.1:8787/mcp.

Development

packages/core/         planning engine (TypeScript, zero dependencies) + unit tests
packages/mcp-server/   MCP server: tools, text rendering, reminders, .ics, HTTP handler
  src/worker.ts        Cloudflare Workers entry
  src/node.ts          Node.js entry
skills/openjetlag/     Agent Skill for coaching behaviour

npm install
npm test          # engine unit tests + end-to-end MCP protocol tests
npm run typecheck

Contributions are welcome, especially from people who know circadian science. Please open an issue before large changes to the planning model, and include tests.

Roadmap

• Public hosted endpoint

• Privacy-preserving usage metrics (aggregate counts only)

• Adaptive re-planning from reported sleep ("I only slept 4 hours")

• Pre-trip shifting that accounts for early departures

• npm package for the engine

Background

OpenJetLag started as a jet lag web app (willbuildtolast/openjetlag). This repository refocuses it on agents: the engine was rewritten and the UI dropped, because your agent is now the interface.

License

MIT