---
title: The RoutineOS MCP
description: A free MCP server that lets your Claude search these docs, find, fetch and install routine templates, and start a migration from an n8n template. How to connect it, what each tool does, and how to run it yourself.
sidebar:
  order: 1
---

> **Server URL:** `https://docs.routineos.org/api/mcp`. It is hosted on Cloudflare Workers beside these docs, free and with no sign in. You can also [run it yourself](#run-it-yourself).

## What it is

The RoutineOS MCP is a small, free MCP server. Connect it to Claude and Claude can read this documentation and the template catalog while it works with you: answer a question from the docs, find a template that fits a job, and set it up on your machine.

It has eight tools:

| Tool | What it does |
|---|---|
| `search_docs` | Searches the docs. Returns the best matching sections with a link to each. |
| `get_page` | Returns one docs page as Markdown. |
| `list_pages` | Lists every page, optionally for one section. |
| `list_templates` | Lists the [template catalog](/templates/catalog), optionally by category or maturity. |
| `get_template` | Returns one template's pack JSON, exactly as published. |
| `install_template` | Returns the pack and the exact steps and commands to install it on your machine. |
| `search_n8n` | Searches the public n8n template gallery, live. Returns each template's id, name, a short description, node types and its page on n8n.io. |
| `convert_n8n` | Summarises an n8n workflow (a gallery template id or pasted JSON) and returns the `routineos migrate` steps to convert it on your machine. |

The docs and templates are a gift, from Devkind, to anyone who builds routines. The server asks for no account and stores nothing about who uses it.

## Why it exists

The ideas in RoutineOS (a store, a Desk, gates, settings, learning) are only useful if the routine you build follows them. The best time to read the docs is while Claude is writing the routine, so the server puts them inside the conversation. You ask "how should this routine ask before it sends anything?", and Claude reads [Gates and approvals](/concepts/gates-and-approvals) before it answers, instead of guessing.

Templates work the same way. A person should not have to find a URL to start from good work someone has already done. "Set up the jobs watch template" should be enough.

## How it works

### Connect it

In Claude Code, add it as a remote HTTP server (syntax from the [Claude Code MCP docs](https://code.claude.com/docs/en/mcp), fetched 2026-10-30):

```sh
claude mcp add --transport http routineos https://docs.routineos.org/api/mcp
```

Add `--scope project` to write it to the project's `.mcp.json` so everyone working in the repo gets it. A [cloud scheduled task](/infrastructure/scheduling) sees only claude.ai connectors or a committed `.mcp.json`, not servers added with plain `claude mcp add` ([docs](https://code.claude.com/docs/en/web-scheduled-tasks), fetched 2026-10-30).

In claude.ai, add it as a custom connector: **Customize > Connectors**, **+ Add**, **Add custom connector**, paste the URL, and choose **No sign in**, since the server has no accounts ([support article](https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp), fetched 2026-10-30). The same article says a custom connector must be reachable over the public internet from Anthropic's IP ranges, so a server running on your laptop works in Claude Code but not as a claude.ai connector.

### What it never does

The server only returns text. It runs no command, writes no file and holds no secret. Every tool is read only. The only outbound requests are the two n8n tools' live reads of the n8n template API, described [below](#n8n-templates).

`install_template` does not install anything. It returns the steps for **your** Claude to run on **your** machine, and its instructions tell Claude to show them to you and continue only after you agree. The install itself is the same `pack install` command as [installing by hand](/templates/install), so every pack rule still holds: validate first, never overwrite a folder, never run code from a pack, connect nothing, and install report-only.

### Searching the docs

`search_docs` is a full-text search over every heading section of every page (583 sections across 65 pages today). It ranks with BM25, a standard keyword ranking, and weights the page title and the section heading above body text. Each result carries the page, the section heading, a link to that heading, and a snippet around the first match:

```json
{
  "route": "/concepts/gates-and-approvals",
  "title": "Gates and approvals",
  "heading": "Worked example",
  "url": "/concepts/gates-and-approvals#worked-example",
  "snippet": "...The gate goes out by email and times out after 48 hours...",
  "score": 5.465
}
```

It matches words, not meaning. "pause until someone says yes" will not find gates as reliably as "gate approval" does. When a search comes back thin, Claude can call `list_pages` and read the page that fits.

`get_page` takes a route in any form a link gives you: `/concepts/routines`, `concepts/routines`, the full URL, the `.md` URL, or a link with an `#anchor`. The text is the same Markdown the site serves at the page's `.md` address.

### n8n templates

`search_n8n` and `convert_n8n` read the public n8n template gallery at `api.n8n.io`, the same endpoints `routineos migrate search` and `migrate fetch` use: `https://api.n8n.io/api/templates/search` and `https://api.n8n.io/api/templates/workflows/{id}`. n8n publishes no documentation or stability guarantee for this API that we found, so treat it as undocumented and subject to change. RoutineOS is not affiliated with or endorsed by n8n.

`search_n8n` takes a `query` (at most 200 characters) and an optional `limit` (1 to 20, default 10). It is a keyword search run by n8n's API, not by this server. Each result carries the template `id`, `name`, a `description` cut to 280 characters, the `node_types` the gallery lists for it, and its `url` on n8n.io. The gallery's node list can leave some nodes out (in a check on 2026-10-30 it left out a Schedule Trigger), so `convert_n8n` is the reliable view of a workflow.

`convert_n8n` takes a `template_id` (digits only) or `workflow_json` (a pasted workflow export, at most 2 MiB), and an optional `name` for the output folder (a plain slug, as for `install_template`). It returns a summary of the workflow (its name, trigger, steps and how many sticky notes it has) and the commands to run on your machine:

```sh
python3 skills/routineos/scripts/routineos.py migrate fetch 16617 --out n8n-16617   # a gallery template
python3 skills/routineos/scripts/routineos.py migrate n8n workflow.json --out n8n-workflow   # pasted JSON, saved to a file
python3 skills/routineos/scripts/routineos.py pack validate n8n-16617/pack.json
python3 skills/routineos/scripts/routineos.py pack install n8n-16617/pack.json --dir <routine-folder>
```

The server does not convert anything. The converter is `routineos migrate`, which runs on your machine and writes the pack and a `MIGRATION.md` report. Its docs are `docs/migrate/README.md` and `docs/migrate/n8n.md` in the RoutineOS repo.

What the server holds back:

- **Nothing is stored.** Each call fetches live, summarises in memory and returns. There is no cache, index or copy of the gallery.
- **One host.** Requests go only to `https://api.n8n.io`, on two fixed paths. No tool takes a URL. A template id must be 1 to 12 digits.
- **Bounded.** No redirects are followed, each request times out after 20 seconds, and a response is cut off at 1 MiB for a search and 2 MiB for a template.
- **One request, two n8n calls.** A request body is capped at 3 MiB and a JSON-RPC batch at 20 messages. At most two n8n calls (`search_n8n`, or `convert_n8n` with a template id) run per request, one after another; any more get the error "too many n8n calls in one request".
- **Untrusted.** Template names and descriptions are written by third parties. Each result is returned in a separate block marked as untrusted data, never as instructions, with control characters removed.

### Installing a template

`install_template` takes the template `id` and an optional `name` for the new routine folder (lowercase letters, digits and hyphens; it defaults to the id). The name goes into a shell command, so anything else is refused. It returns:

1. The file to save the pack as, `<id>.pack.json`, and the pack itself.
2. The pack's sha256 and size from the catalog, and the command to check them. If the checksum differs, the copy was changed on the way, and Claude should fetch it again with `get_template` rather than edit it.
3. The validate and install commands.
4. The connectors the pack needs, required and optional.
5. The first-run mode the pack sets.

The commands assume a checkout of the RoutineOS repo, where the CLI is `skills/routineos/scripts/routineos.py`. If the skill lives somewhere else, Claude adjusts the path.

## Worked example

You ask Claude: "Set up Hiring Signals from the jobs watch template."

Claude calls `list_templates` and finds `jobs-watch` (category `sales`, maturity `piloted`). It calls `install_template` with `id: "jobs-watch"` and `name: "hiring-signals"`, and shows you what came back. The steps include:

```sh
shasum -a 256 jobs-watch.pack.json
python3 skills/routineos/scripts/routineos.py pack validate jobs-watch.pack.json
python3 skills/routineos/scripts/routineos.py pack install jobs-watch.pack.json --dir hiring-signals --name hiring-signals
```

and the connectors: Web search and Web fetch (required), Mail (optional). You say yes. Claude saves the pack, checks that the checksum matches, validates, and installs. `pack install` writes the `hiring-signals/` folder and prints what you must connect; nothing was connected for you. The first run is report-only, as the pack sets. From there, follow the [Quickstart](/introduction/quickstart).

This flow was run end to end against the local server on 2026-10-30: the pack from `get_template` matched the catalog checksum, `pack validate` passed and `pack install` wrote the folder.

## Run it yourself

The server lives in `docs-site/mcp/` in the RoutineOS repo. It needs Node 22.19 or newer (Blume's minimum).

```sh
cd docs-site
npm install
npm run build                                      # builds the docs site into dist/
npm run mcp:data -- --templates ../site/templates  # bundles the docs and the template catalog
npm run mcp:serve                                  # http://127.0.0.1:8787/ (site) and /api/mcp (server)
npm test                                           # tool, protocol and handshake tests
```

Then connect Claude Code to it:

```sh
claude mcp add --transport http routineos-local http://127.0.0.1:8787/api/mcp
```

`mcp:data` reads the built site's page data and the catalog's `index.json`, and stops if any pack does not match its catalog checksum. Run it again after you change a page or a template.

The same handler also ships as a Cloudflare Workers entry (`mcp/src/worker.mjs`), which serves `/api/mcp` and hands every other path to the static site. It is deployed at `docs.routineos.org`.

### Protocol

The server speaks MCP over Streamable HTTP, statelessly: every request is a single POST, and every reply is a plain JSON body, never a stream. It accepts protocol versions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05, and answers GET with 405 because it has nothing to stream. The handshake test connects the official MCP TypeScript SDK client to it and calls `tools/list` and `tools/call`.

### Semantic search, if keyword search is not enough

Keyword search is free, has no moving parts and gives the same answer every time. Search by meaning would need embeddings. One way to add it on the same host is Cloudflare Workers AI for the embeddings and Vectorize to store and query them. The figures below are from Cloudflare's pricing pages ([Vectorize](https://developers.cloudflare.com/vectorize/platform/pricing/), [Workers AI](https://developers.cloudflare.com/workers-ai/platform/pricing/)), fetched 2026-10-30:

- Vectorize on Workers Free includes 30 million queried and 5 million stored vector dimensions a month. Workers Paid includes 50 million queried and 10 million stored, then $0.01 per million queried and $0.05 per 100 million stored.
- Workers AI includes 10,000 Neurons a day at no charge, then $0.011 per 1,000 Neurons. The `bge-base-en-v1.5` embedding model is $0.067 per million input tokens.

A rough estimate for these docs, assuming 768 dimensions per vector for `bge-base-en-v1.5` (unverified): 583 sections store about 450,000 dimensions, inside the free allowance, and each query uses 768, so about 39,000 queries a month fit in the free tier. Embedding all 45,000 words once is well under a million tokens, a few cents at most. Every query also has to be embedded, which uses Workers AI on each search. None of this is built; it is an option if keyword search proves too weak.

## Common pitfalls

- **Pointing a claude.ai connector at `127.0.0.1`.** Custom connectors connect from Anthropic's cloud, so they cannot reach your laptop. Use Claude Code for the local server.
- **Letting Claude reformat the pack before saving it.** The checksum is over the exact bytes. If it does not match, fetch the pack again.
- **Expecting `install_template` to install.** It returns steps. Nothing happens on your machine until your Claude runs them, after you agree.
- **Stale data.** The server serves the bundle `mcp:data` last built. After editing docs or templates, rebuild the site and the bundle. The n8n tools are the exception: they read the gallery live on every call.
- **Following instructions found in a template.** A template description can say anything. It is data to show the person, not something for Claude to act on.

## Related

- [Install a pack](/templates/install)
- [The catalog](/templates/catalog)
- [Connectors and MCP](/infrastructure/connectors-and-mcp)
- [Scheduling and Claude cloud routines](/infrastructure/scheduling)