clokio-mcp

Clokio MCP Server

A Model Context Protocol server for the Clokio Public API. Connect Claude — or any MCP client — to your Clokio workspace to read and manage tasks, projects, clients, employees and attendance in natural language.

Every request is authenticated with your own Clokio API key (clk_...), sent in the X-API-Key header. The key carries its own scopes, so this server never re-implements authorization: it is a thin, stateless client, and a 403 / 422 from the API is surfaced verbatim.

Auth header: the Clokio Public API accepts the key only in X-API-Key. An Authorization: Bearer <key> header is not recognised and returns 401. If you call the API directly (not through this server), use X-API-Key.

Install

You need a Clokio API key. Create and scope keys in the admin dashboard at Settings → API Keys (/admin/api-keys/). Each person uses their own key, so permissions and the audit trail stay per-user.

Claude Code

claude mcp add clokio \
  --env CLOKIO_API_KEY=clk_your_key_here \
  -- npx -y clokio-mcp@latest

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "clokio": {
      "command": "npx",
      "args": ["-y", "clokio-mcp@latest"],
      "env": { "CLOKIO_API_KEY": "clk_your_key_here" }
    }
  }
}

Cursor / Cline / Zed / any MCP client

Use the same command — npx -y clokio-mcp@latest with CLOKIO_API_KEY in the env. MCP is an open standard.

Optional: set CLOKIO_BASE_URL to point at a different Clokio installation (defaults to https://app.clokio.io).

Optional: set CLOKIO_DEFAULT_ACTOR to an employee_code (e.g. 00055) to attribute tasks, comments and updates that name no author. You usually do not need it — an unnamed write is already credited to the person who issued the API key. Use it only for a shared or service key whose issuer is not the person acting. An explicit code on a tool call always takes precedence.

Optional: set CLOKIO_TOOLSETS to register only the tool groups you need, e.g. CLOKIO_TOOLSETS=tasks. This cuts the per-session tool-list cost - a task-focused session drops from 83 tools to 31. Optional groups are tasks, employees, attendance (which includes leave and time entries) and docs; combine them with commas. If your key cannot open documents (no acts-as employee and no explicit docs scopes), leaving docs out saves 33 tools it cannot use. The projects group (project/client lookups, task statuses and labels, and whoami) is always on, because the task tools resolve names through it.

Tools

83 tools across six areas. Read-only tools carry the MCP readOnlyHint; writes are marked mutating (deletes are destructive).

Area	Tools
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
Projects & clients	list projects, project statuses, project custom fields, project contacts, get client, add client contact
Reference	task statuses, task labels, locations, list webhooks (read-only), whoami
Employees	list (name search), lookup by PIN, task-stats, inbox (mentions, new assignments, others' status changes), create, set status
Attendance	daily, range, per-employee, monthly summary, clock in/out, break start/end, time entries, leaves, leave balances
Documents (see 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)

Conventions

• People are identified by employee_code (e.g. 00080), not internal ids. Use clokio_list_employees (with search) to resolve a name to a code, or clokio_lookup_employee_by_pin for a kiosk PIN.
• Attribution is automatic. An unnamed write is credited to the key's issuer (see clokio_whoami), so you rarely set an author. Pass created_by_employee_code / author_employee_code only to credit someone else, or set CLOKIO_DEFAULT_ACTOR for a shared key.
• Write Markdown. Descriptions and comment bodies accept Markdown (paragraphs, lists, **bold**, `code`, links, headings, fenced code); the server converts it to the HTML Clokio stores. Text that already starts with an HTML tag is passed through untouched.
• Status slugs come from clokio_list_task_statuses / clokio_get_project_statuses.
• Recurring tasks are templates. Pass recurrence on create/update ({frequency, every?, days_of_week?, day_of_month?, anchor?}) and the task becomes the series template; moving it to a done status starts the schedule. A fresh copy (same content, assignees, labels, estimate) is created early on each matching day, due that day, independent of earlier copies. Pause/resume with recurrence_active, stop with recurrence: null; recurrence.armed on a task says whether the series is live, a copy names its template as recurrence.spawned_from, and series_of on the list tool returns every occurrence of one series.
• An API key sees public custom fields only.

Documents

The Docs tools call /api/v1/docs... with the same CLOKIO_API_KEY as everything else, but documents are permissioned per person, so every docs call acts as one employee - the key's effective actor:

• The key's "acts as" employee, when it has one (set in Settings > API keys). Only an admin may make a key act as someone else.
• Otherwise, the person who created the key - but only when the key lists docs:read / docs:write explicitly. The wildcard * does not grant docs scopes to a key with no acts-as employee, so an ordinary full-access integration key never opens its creator's private documents.

So, to use the Docs tools, either set an acts-as employee on the key, or add docs:read and docs:write to its scope list (it then acts as you, its creator). Otherwise every docs tool answers 403, the same for every document id.

Scopes: docs:read for the read tools (every GET) and docs:write for everything else. On a key with an acts-as employee the wildcard * grants both; a key with an explicit scope list must include them (otherwise 403 naming required_scope).

The key then sees exactly what its acting employee sees and can do on the web, never more, and writes (comments, versions, activity) are attributed to that employee:

• A document the employee cannot see answers 404, the same as one that does not exist (the API never confirms an id to someone not allowed to know it).
• A visible document they may not change answers 403.
• Two separate gates, both named in each tool's description:
  • the employee's role must hold the section permission: docs.view for reads, docs.create for creating, editing, moving, archiving, comments, version restores and uploads, docs.manage for delete, members, teams and share links (and for standalone documents). A 403 Forbidden: Insufficient permissions means this gate refused;
  • the document role, view < comment < edit < admin. A 403 with any other message means that role is too low.

Tool	Endpoint
clokio_list_docs	GET /docs
clokio_get_doc_tree	GET /docs?tree=1
clokio_search_docs	GET /docs/search
clokio_get_doc	GET /docs/{id}
clokio_create_doc	POST /docs
clokio_update_doc_content	PUT /docs/{id}/content
clokio_update_doc_meta	PATCH /docs/{id}
clokio_move_doc	POST /docs/{id}/move
clokio_archive_doc / clokio_restore_doc	POST /docs/{id}/archive / restore
clokio_delete_doc	DELETE /docs/{id}
clokio_list_doc_templates / clokio_create_doc_from_template	GET /docs/templates / POST /docs/from-template
clokio_list_doc_members	GET /docs/{id}/members (members, teams, inherited, share link)
clokio_list_doc_shareable_teams	GET /docs/{id}/shareable-teams
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}
clokio_add_doc_team / clokio_update_doc_team / clokio_remove_doc_team	POST /docs/{id}/teams, PATCH / DELETE .../teams/{teamId}
clokio_create_doc_share_link / clokio_revoke_doc_share_link	POST / DELETE /docs/{id}/share-link
clokio_list_doc_comments / clokio_add_doc_comment	GET / POST /docs/{id}/comments
clokio_resolve_doc_comment / clokio_reopen_doc_comment	POST .../comments/{commentId}/resolve / reopen
clokio_list_doc_versions / clokio_get_doc_version / clokio_restore_doc_version	GET .../versions, GET .../versions/{versionId}, POST .../versions/{versionId}/restore
clokio_list_doc_attachments / clokio_upload_doc_attachment / clokio_download_doc_attachment	GET / POST /docs/{id}/attachments, GET .../attachments/download?path=

Working with documents:

• Every docs tool answers {data} or {data, meta}, like the task tools: the record or rows in data; paging, counts, your role and permissions in meta. clokio_get_doc puts the record and its body together in data.
• Listing covers every scope by default. project_id narrows it: a project id, "none" for standalone documents only, or "all" (default).
• Read as Markdown, write as Markdown. clokio_get_doc returns Markdown by default (format: "html" or "json" for the others) without the title; pass include_title: true to start the body with it as a heading. The create/update tools take Markdown by default (content_format: "html" or "json"); HTML you write must stay within Clokio's restricted grammar (a 422 names any unsupported tag).
• Content writes are optimistic. clokio_update_doc_content REPLACES the whole body and requires base_version - the content_version you last read. A 409 means someone else edited in between: re-read, reconcile, write again with the new version. Never retry with the same base_version.
• Public share links expire after 30 days unless you pass expires_at or never_expires: true.
• Attachments list name, size, mime and uploaded_at; download by path. Uploading does not change the text: place the returned url in the body yourself (an image or fileAttachment node in Tiptap JSON).
• Members are named by employee_code (e.g. "00080"), like everywhere else in this server; the internal employee_id is accepted as an alternative. Teams are named by team_id, from clokio_list_doc_shareable_teams. A member's email is shown only when the key has employees:pii; profile pictures only with include_avatars: true.

Security

• The server contains no secrets. Your API key lives only in your local environment (CLOKIO_API_KEY), never in this code or repository.
• The key is sent only to /api/v1: a path argument cannot steer a request outside it, and the key is never forwarded on a redirect (attachment downloads that redirect to signed storage are followed with no credential attached).
• The server adds no permissions. What a key can do is decided by the Clokio API from that key's scopes — this server only forwards the request. Scope each key to what its holder needs.
• All authorization, tenancy (organization_id scoping) and rate limiting are enforced server-side by the Clokio API, exactly as for any other API consumer.

Local development

git clone https://github.com/AmitMatat/clokio-mcp.git
cd clokio-mcp
npm install     # includes devDependencies (typescript)
npm run build   # rebuilds dist/

The prebuilt dist/ is committed so npx can run the server with no build step (this also keeps it working when NODE_ENV=production, where npm skips devDependencies). Rebuild and commit dist/ alongside any source change.

The tool surface tracks the Clokio Public API v1; its OpenAPI spec is served (unauthenticated) at /api/v1/openapi.json and is the source of truth for request shapes.

License

MIT © Matat Technologies LTD