tidee
Add items to your tidee workspace from ordinary language, read what is there, and mark things done.
Open source Open in the app JSON README (API)
About
Add items to your tidee workspace from ordinary language, read what is there, and mark things done.
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- com.tidee
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 1.0.2
- Added
- 2026-09-04 10:01:01
- Updated
- 2026-09-04 20:00:53
- Origin id
com.tidee/tidee
README
# tidee-life-mcp
An [MCP](https://modelcontextprotocol.io) 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:
```sh
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
1. 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.
2. Add the server to your MCP client's config:
```json
{
"mcpServers": {
"tidee": {
"command": "npx",
"args": ["-y", "tidee-mcp"],
"env": { "TIDEE_API_TOKEN": "tdl_…" }
}
}
}
```
3. 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
```sh
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:
```sh
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
```sh
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.