An MCP server for tidee. It lets an assistant add items to your workspace, read what is there, and mark things done — without you switching to the app to write it down.

Which one do you want?

There are two ways to connect, and most people want the hosted one.

Hosted — point your client at https://app.tidee.com/mcp. Nothing to install, and no token to copy: your client registers itself, tidee asks you to approve it in the browser, and that is the whole setup. In Claude Code that is one line:

claude mcp add --transport http tidee https://app.tidee.com/mcp

This package — a local server over stdio, for clients that do not speak HTTP MCP, or when you want to point at a development server. It needs Node and a token you paste into a config file.

Setup

In tidee, open Application Settings → Integrations and create a token. Give it only the access the assistant needs:

Access	Tools it enables
Add new items	`capture`, `create_item`
Read items	`list_boxes`, `list_items`
Edit and complete existing items	`complete_item`

The token is shown once. Copy it then.

Add the server to your MCP client's config:

{
  "mcpServers": {
    "tidee": {
      "command": "npx",
      "args": ["-y", "tidee-mcp"],
      "env": { "TIDEE_API_TOKEN": "tdl_…" }
    }
  }
}

Restart the client.

Environment

Variable	Required	Default
`TIDEE_API_TOKEN`	yes	—
`TIDEE_API_URL`	no	`https://app.tidee.com`

TIDEE_API_URL exists for pointing at a local server during development. Leave it unset otherwise.

Releasing

pnpm run mcp:release                   # from the repo root
cd packages/tidee-life-mcp && npm publish

mcp:release bumps the patch version and records a fingerprint of everything that determines what gets published — this package's source, tidee-life-core/mcp, and the runtime dependencies. CI verifies that record on every pipeline.

That check exists because there are two of these in the wild: the hosted endpoint at app.tidee.com/mcp, which updates on every deploy, and this package, which updates only when somebody remembers. Sharing the tool definitions stops the source drifting; nothing stops the artefacts drifting, and when they do it is silent — package users just get older tools than URL users. Editing a tool description in tidee-life-core/mcp is enough to cause it, and that file is nowhere near this package.

Publishing stays manual: it needs credentials and a 2FA code, the version is claimed forever, and unpublishing is heavily restricted after 72 hours.

The MCP registry

server.json is the registry entry. It lists BOTH ways to connect — the hosted endpoint under remotes, and this package under packages — so a client can prefer whichever suits it. The hosted one needs no token; this one does, which is why only the package entry declares TIDEE_API_TOKEN.

Three things must agree, or publishing is rejected:


`server.json` → `name`	`package.json` → `mcpName`
`server.json` → `version`	`package.json` → `version`
`server.json` → `packages[0].version`	`package.json` → `version`

mcpName is how the registry verifies ownership: it checks that the npm package claims the same name the registry entry does, which stops anyone registering a server pointing at a package they do not own. It therefore has to be inside the published tarball — bump and republish before publishing to the registry, not after.

The com.tidee/ namespace needs DNS authentication (a TXT record on tidee.com) rather than the GitHub flow, so that a listing carries the product's own name rather than a personal account's:

brew install mcp-publisher
mcp-publisher login dns --domain tidee.com
mcp-publisher publish

The registry is in preview and warns about breaking changes, so check the current docs at modelcontextprotocol.io/registry before running it.

Building

pnpm run build

Type-checks, then bundles to a single dist/index.js with esbuild.

The bundling is not an optimisation. The tool definitions — names, schemas, descriptions, and the sentences returned to the model — live in tidee-life-core/mcp, shared with the hosted server so the two cannot drift. That is a private workspace package, so it cannot be a dependency of anything published; inlining it means what ships depends only on @modelcontextprotocol/sdk and zod, while there is still exactly one definition of the tools.

Tools

capture — the one to reach for. Takes a whole thought in ordinary language and lets tidee work out the separate items, which box each belongs in, and any dates. "Book the MOT and call Sam about Friday" becomes two items, filed.
create_item — one item with an exact title, for when the wording is already decided.
list_boxes — the boxes items are filed in, with their ids.
list_items — read or search items.
complete_item — mark one done.

Notes

Every tool is a single call to tidee's public API. Planning, filing and the never-lose fallback all happen server-side, which is why this server holds no logic worth configuring: it is a client, not a second copy of the app.

A capture that cannot be interpreted is never discarded — it is stored verbatim as one item, and the tool says so.

Captures made through this server count towards the account's capture allowance, exactly as they would in the app.

If a token is revoked or expires the tools stop working immediately and say why. Create a new one in Settings and update the config.