Rhylthyme MCP server

A Model Context Protocol server for schedules that a person executes: cooking several dishes so they finish together, running a bench protocol with overlapping incubations, calling an event, running a workout. An agent describes the process, the server validates and analyzes the resulting program, and publishes it as a live timeline on rhylthyme.com that the person follows on their phone.

This repository is the source of the server that runs at mcp.rhylthyme.com. It is the same code as mcp-api/ in the rhylthyme-server application, copied here with the static assets it needs so it can be read, tested and self-hosted.

Try it: ask for a workout

Connect the server (in Claude Code, /plugin marketplace add rhylthyme/rhylthyme-mcp then /plugin install rhylthyme@rhylthyme; anywhere else, add https://mcp.rhylthyme.com/gym/mcp as a connector), then say what you want in plain words:

Two of us in a garage gym: one kettlebell, one pull-up bar, one jump rope. Thirty minutes, two rounds, and nobody stands around waiting for equipment. Make it a Rhylthyme timeline.

You write no JSON. The assistant does, and the server keeps it honest. With that prompt Claude made three tool calls:

                0                       15m                    30m
Alex           │░Warm-…░▒S…▒░Pu…░▒Ju…▒░░░▒Sw…▒░Pu…░▒Ju…▒░░░▒St…▒│
Sam            │░Warm-…░▒P…▒░Ju…░▒Sw…▒░░░▒Pu…▒░Ju…░▒Sw…▒░░░▒St…▒│

Ask "show me a picture" and preview_timeline returns an image in the chat. For one coloured by station, which makes the rotation obvious, save the program the assistant wrote (ours is examples/recipe/garage-circuit.json) and run:

npx -y github:rhylthyme/rhylthyme-timeline garage-circuit.json -o garage-circuit.png \
  --style web --palette tableau --color-by task

Then push on it: "add a third person", "we only have 20 minutes", "swap the rope for burpees". The assistant edits the program and the server checks it again.

This repository and rhylthyme-cli-runner

Two repositories do related things and are easy to confuse. This one is the server an AI assistant talks to. rhylthyme-cli-runner is the command a person types.

How they fit together: the command-line tool is one of this server's clients. rhylthyme analyze, publish, generate and mcp-test are MCP calls to mcp.rhylthyme.com; rhylthyme validate, run, runs and calibrate never touch the network. Each has its own validator for the same program schema (JavaScript here, Python there), so a program is checked again when it is published.

Use this repository to connect an assistant, to read or self-host the server, or to change a tool. Use rhylthyme-cli-runner if you have a program file and a terminal, want timers in the terminal, or keep run records.

Two names to keep apart: rhylthyme-mcp on PyPI is this server's stdio bridge (command rhylthyme-mcp, source in python/); rhylthyme-cli-runner on PyPI is the command-line tool (command rhylthyme). The program format itself is defined in rhylthyme-spec, with examples in rhylthyme-examples.

Endpoints

Transport: Streamable HTTP, stateless. No sign-in is needed for the public catalog or the pure tools; account tools use the person's Rhylthyme account through OAuth 2.1, or a pasted token from the login tool in clients without OAuth. Server instructions describing the workflow are sent at initialize.

Quickstart: timelines from the command line

The rhylthyme CLI can drive this server directly: describe what you need in plain language and get back a live timeline URL, a program file, or both.

pip install rhylthyme                        # Python 3.12+
rhylthyme login                              # opens rhylthyme.com in your browser
rhylthyme generate "roast chicken, potatoes and green beans for 6" \
    -e kitchen --by 19:00 --with "one oven, four burners, one cook"

login signs you in through the browser and hands the session back to a one-shot listener on 127.0.0.1. It is stored in ~/.config/rhylthyme/credentials.json (mode 0600) and renews itself, so you only log in once. generate then calls two tools on this server:

1. import_text on the endpoint for -e (/kitchen/mcp, /lab/mcp, …) turns the request into a validated multi-track program. It runs four model turns server-side, which is why it needs a sign-in; it takes 20–60 seconds and is capped per day.
2. visualize_schedule publishes that program and returns the live-timeline URL on the matching subdomain.

It prints the ASCII Gantt, the itinerary and the URL. More examples:

# A lab protocol from a file; save the program and run it in the terminal
rhylthyme generate -e lab -f western_blot.txt -o blot.json --run

# Pipe a run sheet in; print only the URL
pbpaste | rhylthyme generate -e events --by "doors at 18:30" -q

# Program JSON only, no published timeline; machine-readable output
rhylthyme generate -e gym "45 minute upper-body circuit, two people, one bench" --no-publish --json

To check a server (this one, or your own deployment) end to end:

rhylthyme mcp-test                                   # all five hosted endpoints, read-only
rhylthyme mcp-test --url http://localhost:3000/mcp -e generic --publish

rhylthyme whoami shows the stored sign-in; rhylthyme logout forgets it. On a machine without a browser, set RHYLTHYME_TOKEN to an access token from https://www.rhylthyme.com/mcp/auth (it lasts about an hour), or run rhylthyme login --token <token>. RHYLTHYME_MCP_URL points the CLI at a self-hosted server.

Connect

Claude Code

claude mcp add --transport http rhylthyme https://mcp.rhylthyme.com/mcp
claude mcp add --transport http rhylthyme-kitchen https://mcp.rhylthyme.com/kitchen/mcp

Claude Desktop / claude.ai: Settings → Connectors → Add custom connector → paste one of the URLs above. Public tools work immediately; run login only to save to your own account.

Claude Code plugin (the hosted server plus a skill that teaches Claude to author, validate and analyze schedules):

/plugin marketplace add rhylthyme/rhylthyme-mcp
/plugin install rhylthyme@rhylthyme