OpenJetLag MCP
README.md
# OpenJetLag MCP
[](https://github.com/willbuildtolast/openjetlag-mcp/actions/workflows/ci.yml)
[](LICENSE)
**Turn your personal AI agent into a jet lag coach.**
OpenJetLag is an open-source [Model Context Protocol](https://modelcontextprotocol.io) 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.
[中文说明](README.zh-CN.md)
```
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](#self-hosting) (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`](skills/openjetlag/SKILL.md) is a playbook in the open [Agent Skills](https://agentskills.io) 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.
## 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`](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](packages/core/README.md) 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):
```sh
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`](.github/workflows/deploy.yml). A step-by-step guide in Chinese is in [docs/DEPLOY.zh-CN.md](docs/DEPLOY.zh-CN.md).
**Node.js** (any VPS or container, Node 20+):
```sh
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](https://github.com/modelcontextprotocol/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
```
```sh
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](https://github.com/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](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data