Rhylthyme

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.ai, Claude Desktop or mobile, add Rhylthyme from the Claude Connectors Directory; 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

Two repositories do related things and are easy to confuse. This one is the server an AI assistant talks to. rhylthyme (formerly 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 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 on PyPI is the command-line tool (command rhylthyme; it was published as rhylthyme-cli-runner before 0.5.0). 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 . 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: Customize → Connectors, search for *Rhylthyme* and click Connect. For one of the other URLs above: Customize → Connectors → Add → *Add custom connector* → paste the URL → Continue. 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):

These are two commands. Send the first on its own:

/plugin marketplace add rhylthyme/rhylthyme-mcp

then, once it says the marketplace was added, the second:

/plugin install rhylthyme@rhylthyme

ChatGPT: Settings → Apps & Connectors → Advanced settings → turn on *Developer mode*, then *Create* a connector with one of the URLs above as the MCP server URL. Without a connector ChatGPT cannot call these tools and falls back to browsing the website.

Cursor (.cursor/mcp.json):

{ "mcpServers": { "rhylthyme": { "url": "https://mcp.rhylthyme.com/kitchen/mcp" } } }

Claude API (MCP connector, one request):

import anthropic

client = anthropic.Anthropic() resp = client.beta.messages.create( model="claude-opus-5", max_tokens=16000, betas=["mcp-client-2025-11-20"], mcp_servers=[{"type": "url", "url": "https://mcp.rhylthyme.com/kitchen/mcp", "name": "rhylthyme"}], tools=[{"type": "mcp_toolset", "mcp_server_name": "rhylthyme"}], messages=[{"role": "user", "content": "Plan Thanksgiving for 8 with one oven, dinner at 6pm."}], )

Reviewing an import. review_program (an account tool) has a model read an imported program against its source and return findings: wrong durations, dropped steps, bad ordering, a total that disagrees with the source. Call it after import_from_source or import_text, apply what it says, and validate again.

Clients that can only launch a command: pip install rhylthyme-mcp gives a rhylthyme-mcp command, a stdio bridge that passes every request through to the hosted server (source in python/):

{ "mcpServers": { "rhylthyme": { "command": "rhylthyme-mcp", "args": ["kitchen"] } } }

No MCP client at all (a