{"id":"66a43ce4-e4fc-462c-a11d-a3feba8ef5e5","slug":"amitmatat-clokio-mcp","kind":"mcp","name":"clokio-mcp","summary":"MCP server for the Clokio Public API — manage tasks, projects, attendance and employees from any MCP client.","owner":"AmitMatat","repoUrl":"https://github.com/AmitMatat/clokio-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-09-26T08:24:52.000Z","addedAt":"2026-10-14T11:08:40.668Z","logoUrl":"https://avatars.githubusercontent.com/u/7139198?u=897da88d7473075bb76ec548d6662d034570dbc7&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-17T20:42:00.038Z","sample":false,"url":"https://conduits.dev/tools/amitmatat-clokio-mcp","language":"TypeScript","transports":["stdio"],"install":{"npm":"clokio-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Clokio MCP Server\n\n[![npm version](https://img.shields.io/npm/v/clokio-mcp.svg)](https://www.npmjs.com/package/clokio-mcp)\n[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io)\n\nA [Model Context Protocol](https://modelcontextprotocol.io) server for the\n**[Clokio](https://clokio.io) Public API**. Connect Claude — or any MCP client —\nto your Clokio workspace to read and manage tasks, projects, clients, employees\nand attendance in natural language.\n\nEvery request is authenticated with **your own** Clokio API key (`clk_...`),\nsent in the **`X-API-Key`** header. The key carries its own scopes, so this\nserver never re-implements authorization: it is a thin, stateless client, and a\n`403` / `422` from the API is surfaced verbatim.\n\n> **Auth header:** the Clokio Public API accepts the key only in `X-API-Key`.\n> An `Authorization: Bearer <key>` header is **not** recognised and returns\n> `401`. If you call the API directly (not through this server), use `X-API-Key`.\n\n## Install\n\nYou need a Clokio API key. Create and scope keys in the admin dashboard at\n**Settings → API Keys** (`/admin/api-keys/`). Each person uses their own key, so\npermissions and the audit trail stay per-user.\n\n### Claude Code\n\n```bash\nclaude mcp add clokio \\\n  --env CLOKIO_API_KEY=clk_your_key_here \\\n  -- npx -y clokio-mcp@latest\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"clokio\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"clokio-mcp@latest\"],\n      \"env\": { \"CLOKIO_API_KEY\": \"clk_your_key_here\" }\n    }\n  }\n}\n```\n\n### Cursor / Cline / Zed / any MCP client\n\nUse the same command — `npx -y clokio-mcp@latest` with `CLOKIO_API_KEY` in the env.\nMCP is an open standard.\n\nOptional: set `CLOKIO_BASE_URL` to point at a different Clokio installation\n(defaults to `https://app.clokio.io`).\n\nOptional: set `CLOKIO_DEFAULT_ACTOR` to an `employee_code` (e.g. `00055`) to\nattribute tasks, comments and updates that name no author. You usually do not\nneed it — an unnamed write is already credited to the person who issued the API\nkey. Use it only for a **shared or service key** whose issuer is not the person\nacting. An explicit code on a tool call always takes precedence.\n\nOptional: set `CLOKIO_TOOLSETS` to register only the tool groups you need, e.g.\n`CLOKIO_TOOLSETS=tasks`. This cuts the per-session tool-list cost - a\ntask-focused session drops from 83 tools to 31. Optional groups are `tasks`,\n`employees`, `attendance` (which includes leave and time entries) and `docs`;\ncombine them with commas. If your key cannot open documents (no acts-as\nemployee and no explicit docs scopes), leaving `docs` out saves 33 tools it\ncannot use. The `projects` group (project/client lookups, task statuses\nand labels, and `whoami`) is always on, because the task tools resolve names\nthrough it.\n\n## Tools\n\n83 tools across six areas. Read-only tools carry the MCP `readOnlyHint`; writes\nare marked mutating (deletes are `destructive`).\n\n| Area | Tools |\n|------|-------|\n| **Tasks** | list (with `compact` / `sort` / `updated_since` / `recurring`), get (with `comments_limit`), create, update (incl. recurring series: set a rule, pause/resume, stop), delete, bulk update, set assignees, list/add/edit comments, list attachments (with `is_latest` + `latest_only`), upload, download one (save to disk, or read PDF text / ZIP entries / images / text inline), download all to a folder, activity, list/add/remove dependencies, set custom field |\n| **Projects & clients** | list projects, project statuses, project custom fields, project contacts, get client, add client contact |\n| **Reference** | task statuses, task labels, locations, list webhooks (read-only), whoami |\n| **Employees** | list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status |\n| **Attendance** | daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances |\n| **Documents** (see [Documents](#documents) for who a key acts as) | list, tree, search, get (Markdown / HTML / JSON), create, replace content, update meta, move, archive, restore, delete, templates + create from template, members (by `employee_code`) and teams (list/add/update/remove, shareable teams), public share link, comments (list/add/resolve/reopen), versions (list/get/restore), attachments (list/upload/download) |\n\n### Conventions\n\n- **People are identified by `employee_code`** (e.g. `00080`), not internal ids.\n  Use `clokio_list_employees` (with `search`) to resolve a name to a code, or\n  `clokio_lookup_employee_by_pin` for a kiosk PIN.\n- **Attribution is automatic.** An unnamed write is credited to the key's\n  issuer (see `clokio_whoami`), so you rarely set an author. Pass\n  `created_by_employee_code` / `author_employee_code` only to credit someone\n  else, or set `CLOKIO_DEFAULT_ACTOR` for a shared key.\n- **Write Markdown.** Descriptions and comment bodies accept Markdown (paragraphs, lists,\n  `**bold**`, `` `code` ``, links, headings, fenced code); the server converts it to the HTML\n  Clokio stores. Text that already starts with an HTML tag is passed through untouched.\n- **Status slugs** come from `clokio_list_task_statuses` /\n  `clokio_get_project_statuses`.\n- **Recurring tasks are templates.** Pass `recurrence` on create/update\n  (`{frequency, every?, days_of_week?, day_of_month?, anchor?}`) and the task\n  becomes the series template; **moving it to a done status starts the\n  schedule**. A fresh copy (same content, assignees, labels, estimate) is\n  created early on each matching day, due that day, independent of earlier\n  copies. Pause/resume with `recurrence_active`, stop with `recurrence: null`;\n  `recurrence.armed` on a task says whether the series is live, a copy names\n  its template as `recurrence.spawned_from`, and `series_of` on the list tool\n  returns every occurrence of one series.\n- An API key sees **public custom fields only**.\n\n## Documents\n\nThe Docs tools call `/api/v1/docs...` with the same `CLOKIO_API_KEY` as\neverything else, but documents are permissioned per **person**, so every\ndocs call acts as one employee - the key's **effective actor**:\n\n- **The key's \"acts as\" employee**, when it has one (set in\n  **Settings > API keys**). Only an admin may make a key act as someone else.\n- **Otherwise, the person who created the key** - but only when the key lists\n  `docs:read` / `docs:write` **explicitly**. The wildcard `*` does not grant\n  docs scopes to a key with no acts-as employee, so an ordinary full-access\n  integration key never opens its creator's private documents.\n\nSo, to use the Docs tools, either set an acts-as employee on the key, or add\n`docs:read` and `docs:write` to its scope list (it then acts as you, its\ncreator). Otherwise every docs tool answers `403`, the same for every\ndocument id.\n\n**Scopes:** `docs:read` for the read tools (every `GET`) and `docs:write` for\neverything else. On a key with an acts-as employee the wildcard `*` grants\nboth; a key with an explicit scope list must include them (otherwise `403`\nnaming `required_scope`).\n\nThe key then sees exactly what its acting employee sees and can do on the\nweb, never more, and writes (comments, versions, activity) are attributed to\nthat employee:\n\n- A document the employee cannot see answers **`404`**, the same as one that\n  does not exist (the API never confirms an id to someone not allowed to know it).\n- A visible document they may not change answers **`403`**.\n- Two separate gates, both named in each tool's description:\n  - the employee's **role** must hold the section permission: `docs.view`\n    for reads, `docs.create` for creating, editing, moving, archiving,\n    comments, version restores and uploads, `docs.manage` for delete, members,\n    teams and share links (and for standalone documents). A `403`\n    `Forbidden: Insufficient permissions` means this gate refused;\n  - the **document role**, `view` < `comment` < `edit` < `admin`. A `403`\n    with any other message means that role is too low.\n\n| Tool | Endpoint |\n|------|----------|\n| `clokio_list_docs` | `GET /docs` |\n| `clokio_get_doc_tree` | `GET /docs?tree=1` |\n| `clokio_search_docs` | `GET /docs/search` |\n| `clokio_get_doc` | `GET /docs/{id}` |\n| `clokio_create_doc` | `POST /docs` |\n| `clokio_update_doc_content` | `PUT /docs/{id}/content` |\n| `clokio_update_doc_meta` | `PATCH /docs/{id}` |\n| `clokio_move_doc` | `POST /docs/{id}/move` |\n| `clokio_archive_doc` / `clokio_restore_doc` | `POST /docs/{id}/archive` / `restore` |\n| `clokio_delete_doc` | `DELETE /docs/{id}` |\n| `clokio_list_doc_templates` / `clokio_create_doc_from_template` | `GET /docs/templates` / `POST /docs/from-template` |\n| `clokio_list_doc_members` | `GET /docs/{id}/members` (members, teams, inherited, share link) |\n| `clokio_list_doc_shareable_teams` | `GET /docs/{id}/shareable-teams` |\n| `clokio_add_doc_member` / `clokio_update_doc_member` / `clokio_remove_doc_member` | `POST` / `PATCH` / `DELETE /docs/{id}/members` (by `employee_code`), or `PATCH` / `DELETE .../members/{employeeId}` |\n| `clokio_add_doc_team` / `clokio_update_doc_team` / `clokio_remove_doc_team` | `POST /docs/{id}/teams`, `PATCH` / `DELETE .../teams/{teamId}` |\n| `clokio_create_doc_share_link` / `clokio_revoke_doc_share_link` | `POST` / `DELETE /docs/{id}/share-link` |\n| `clokio_list_doc_comments` / `clokio_add_doc_comment` | `GET` / `POST /docs/{id}/comments` |\n| `clokio_resolve_doc_comment` / `clokio_reopen_doc_comment` | `POST .../comments/{commentId}/resolve` / `reopen` |\n| `clokio_list_doc_versions` / `clokio_get_doc_version` / `clokio_restore_doc_version` | `GET .../versions`, `GET .../versions/{versionId}`, `POST .../versions/{versionId}/restore` |\n| `clokio_list_doc_attachments` / `clokio_upload_doc_attachment` / `clokio_download_doc_attachment` | `GET` / `POST /docs/{id}/attachments`, `GET .../attachments/download?path=` |\n\nWorking with documents:\n\n- **Every docs tool answers `{data}` or `{data, meta}`**, like the task tools:\n  the record or rows in `data`; paging, counts, your role and permissions in\n  `meta`. `clokio_get_doc` puts the record and its body together in `data`.\n- **Listing covers every scope by default.** `project_id` narrows it: a\n  project id, `\"none\"` for standalone documents only, or `\"all\"` (default).\n- **Read as Markdown, write as Markdown.** `clokio_get_doc` returns Markdown by\n  default (`format: \"html\"` or `\"json\"` for the others) without the title;\n  pass `include_title: true` to start the body with it as a heading. The\n  create/update tools take Markdown by default (`content_format: \"html\"` or\n  `\"json\"`); HTML you write must stay within Clokio's restricted grammar (a\n  `422` names any unsupported tag).\n- **Content writes are optimistic.** `clokio_update_doc_content` REPLACES the\n  whole body and requires `base_version` - the `content_version` you last read.\n  A `409` means someone else edited in between: re-read, reconcile, write\n  again with the new version. Never retry with the same `base_version`.\n- **Public share links expire after 30 days** unless you pass `expires_at` or\n  `never_expires: true`.\n- **Attachments** list `name`, `size`, `mime` and `uploaded_at`; download by\n  `path`. Uploading does not change the text: place the returned `url` in the\n  body yourself (an `image` or `fileAttachment` node in Tiptap JSON).\n- **Members are named by `employee_code`** (e.g. `\"00080\"`), like everywhere\n  else in this server; the internal `employee_id` is accepted as an\n  alternative. Teams are named by `team_id`, from\n  `clokio_list_doc_shareable_teams`. A member's `email` is shown only when the\n  key has `employees:pii`; profile pictures only with `include_avatars: true`.\n\n## Security\n\n- The server contains **no secrets**. Your API key lives only in your local\n  environment (`CLOKIO_API_KEY`), never in this code or repository.\n- The key is sent **only to `/api/v1`**: a path argument cannot steer a request\n  outside it, and the key is never forwarded on a redirect (attachment\n  downloads that redirect to signed storage are followed with no credential\n  attached).\n- The server **adds no permissions**. What a key can do is decided by the Clokio\n  API from that key's scopes — this server only forwards the request. Scope each\n  key to what its holder needs.\n- All authorization, tenancy (`organization_id` scoping) and rate limiting are\n  enforced server-side by the Clokio API, exactly as for any other API consumer.\n\n## Local development\n\n```bash\ngit clone https://github.com/AmitMatat/clokio-mcp.git\ncd clokio-mcp\nnpm install     # includes devDependencies (typescript)\nnpm run build   # rebuilds dist/\n```\n\nThe prebuilt `dist/` is committed so `npx` can run the server with no build step\n(this also keeps it working when `NODE_ENV=production`, where npm skips\ndevDependencies). Rebuild and commit `dist/` alongside any source change.\n\nThe tool surface tracks the Clokio Public API v1; its OpenAPI spec is served\n(unauthenticated) at `/api/v1/openapi.json` and is the source of truth for\nrequest shapes.\n\n## License\n\nMIT © Matat Technologies LTD\n"}