Skip to main content
Glama

OpenJetLag MCP

CI License: MIT

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 supplies the expertise: a deterministic planning engine, a ready-made series of proactive check-ins with exact send times and the facts behind each, and guidance that tells the agent to schedule them and write them in its own voice.

Connect it to your agent

Official endpoint:

https://openjetlag-mcp.willbuildtolast.workers.dev/mcp

This is the only URL maintained by this project. You can also host your own (free on Cloudflare).

Quick start for Meta Muse (one message)

Paste this into a Muse chat and approve the connector when Muse asks:

Please add a custom MCP connector for me:
- Name: OpenJetLag
- Transport: remote Streamable HTTP
- URL: https://openjetlag-mcp.willbuildtolast.workers.dev/mcp
- Authentication: none
After it's connected, use it whenever I mention a long flight or jet lag.

Then try: "I fly from New York to London on Nov 10 at 19:00, landing Nov 11 at 07:00. I usually sleep 23:00–07:00. Help me with jet lag and set up reminders." To remove it later: Settings → Connectors.

Agent

How

Meta Muse

Settings → Connectors → Add custom connector, paste the URL. Muse connects from Meta's cloud, so the URL must be public HTTPS.

ChatGPT / Dots

Add it as a custom MCP connector (app) in ChatGPT settings; availability depends on your plan and may require developer mode. Dots use the connectors on your account.

Claude

Settings → Connectors → Add custom connector, paste the URL.

Any MCP client

Streamable HTTP transport, URL ending in /mcp. No authentication.

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: Travel Planning MCP

Tools

All tools are read-only and idempotent.

Tool

What it does

plan_jetlag_trip

Full plan from flight details and usual sleep times, plus scheduled_messages: about 3-4 proactive messages a day (morning briefing, light nudges, wind-down, flight) with exact send times and the facts behind each one (trip moment, body-clock progress, what to do, why); the agent writes and sends the messages in its own voice. starting_from returns only what is still ahead ("what should I do now?").

get_plan_calendar_file

The same plan as an iCalendar (.ics) file with alerts, when the traveller asks for a calendar or the agent cannot schedule messages.

explain_jetlag_topic

Short explanations for "why" questions: overview, light, melatonin, caffeine, naps, direction, flight, safety.

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, fewer if departure is sooner), melatonin (default true, timing only), strategy (auto), language (en or zh), and origin_city, destination_city as the traveller names them.

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

  • 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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables flight planning and aviation operations through intelligent airport resolution, great-circle route calculation, and aircraft performance estimation. Supports 28,000+ airports worldwide and 190+ aircraft types for comprehensive flight planning via natural language.
      46
      64 PyPI
      4
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Provides AI agents with a structured API for travel planning, enabling them to read trip data, search places, calculate routes, and create/validate itinerary change proposals that require explicit human approval before being applied.
      15
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables agents to maintain a persistent, local-first trip ledger with typed tools for managing trips, flights, stays, day plans, people, packing lists, and transit sketches, plus markdown and ICS exports.
      MIT
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables users to calculate chronotype-aligned sleep schedules, optimize 90-minute ultradian cycles, determine caffeine cutoffs, and plan light exposure for better recovery and circadian alignment.
      7
      -