TimeWave MCP server

Lets an AI client (Claude Desktop, IDEs, etc.) manage TimeWave tasks and the time tracker over the Model Context Protocol.

Everything the AI does through this server is attributed to it in TimeWave (viaApi), so those actions show an AI badge in the app.

Setup

Two ways in, and neither asks you to carry a token by hand.

If your client speaks remote MCP (Claude, and most modern clients)

You do not need this package at all. Point the client at:

https://timewave.cloud/api/mcp

It sends you to a TimeWave page where you are already signed in, tells you what is being asked for, and you approve it. Nothing is installed, nothing is copied.

If your client only speaks stdio

npx @timewave-cloud/mcp login --url=https://timewave.cloud

It prints a short code and a link. Approve the code in a browser, and the token arrives here by itself — saved to ~/.timewave/mcp.json with 0600 permissions. Then point your client at this package:

{
  "mcpServers": {
    "timewave": {
      "command": "npx",
      "args": ["-y", "@timewave-cloud/mcp"],
      "env": { "TIMEWAVE_API_URL": "https://timewave.cloud" }
    }
  }
}

That block holds no secret — only a command and an address. The token stays in your own config file, which is the difference between a credential you look after and one that ends up in a screenshot.

npx fetches and runs the server, so there is nothing to clone or install (Node 18+, for global fetch).

A key by hand, for automation

When what you are connecting is a script rather than a person, create a key in TimeWave (user menu → Account & API keys), choose its scopes — read, tasks, timer, docs, secrets — and pass it as TIMEWAVE_API_KEY. The environment wins over a saved login, so anything already set up this way keeps working untouched.

A key acts as you and can never do more than you can; a tool whose scope the key lacks comes back as an error naming the missing scope.

Windows

Claude Desktop on Windows launches MCP servers without a shell and can't resolve bare npx, so use cmd /c:

{
  "mcpServers": {
    "timewave": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@timewave-cloud/mcp"],
      "env": { "TIMEWAVE_API_URL": "https://timewave.cloud" }
    }
  }
}

Fully quit and reopen Claude Desktop after editing the config. If TIMEWAVE_API_URL is omitted it defaults to http://localhost:3000, so tool calls fail with a connection error — set it to your instance.

Local development

To run from a checkout without publishing, point the client at the file directly: "command": "node", "args": ["/absolute/path/to/mcp/server.mjs"] (run npm install in mcp/ first so the SDK and zod resolve).

Publishing (maintainers)

This directory is a self-contained npm package (mcp/package.json, bin: timewave-mcp). To release:

cd mcp
npm publish --access public   # after `npm login`; needs the timewave-cloud npm org

Bump version in mcp/package.json for each release.

Tools

| Tool | What it does | | --- | --- | | guide | How TimeWave works + smart-commit rules (call this first) | | list_projects | Projects + their kanban columns | | list_members | Members (userId for assigning) | | list_tasks | Tasks, filter by projectId / status (open|done|all) | | get_task | One task with checklist + activity | | create_task | Create a task (optional column, dueDate, assigneeId) | | update_task | Edit title/description/priority/assignee/dueDate | | move_task | Move to a column (by name or id) | | complete_task | Mark done / reopen | | comment_task | Add a comment to the activity feed | | delete_task | Permanently delete a task | | start_timer | Start the tracker (optionally on a task) | | stop_timer | Stop the running timer | | timer_status | Is a timer running, and for how long | | log_time | Add a manual entry (durationMinutes) | | list_time_entries | List entries; filter by project/task/date range | | get_time_entry | One time entry by id | | update_time_entry | Edit duration/date/description/project/billable | | delete_time_entry | Permanently delete a time entry | | whoami | Who the key belongs to, and which organization | | add_checklist_item | Add a subtask to a task | | set_checklist_item | Tick a subtask off (or back on) — itemId from get_task | | remove_checklist_item | Remove a subtask | | list_timesheets | Recent weeks: total, status, locked or not | | get_timesheet | One week, day by day and project by project | | submit_timesheet | Hand a week in — this locks it | | withdraw_timesheet | Take a submitted week back (only before review) | | list_docs | Search the knowledge base by title | | get_doc | Read a document with its Markdown | | create_doc | Write a new document | | update_doc | Edit the title, body or visibility | | list_doc_versions | A document's history — who changed what, when | | get_doc_version | Read one earlier version in full | | list_doc_attachments | Files on a document — metadata and a url, never the bytes |

The knowledge base has its own locks

Two of them, and a key can hold the docs scope and still see nothing:

• The organization has to open the base to assistants — Settings → Assistants. Off until somebody turns it on.
• A single page can be held back, along with everything filed under it. To an assistant that page reads exactly as one that does not exist; that is the point, and a not found is not something to route around.

New documents are private — visible only to their author. Pass visibility: "ORG" when writing for the team.

update_doc replaces the whole body. The previous text is kept as a version and can be read back with list_doc_versions / get_doc_version, but somebody has to go and look for it — so change the part that is wrong rather than rewriting a page from memory.

There is no tool for deleting a document, on purpose. Nor for uploading a file: bytes as text is the wrong shape for this protocol. list_doc_attachments hands back a url — fetch it over plain HTTP with the same key, which that route accepts as well as a browser session.

Smart commits

When you commit code to a repository connected to a project, reference the task key in the commit message and TimeWave acts on it during import (manual or the push webhook):

• WAVE-12 — links the commit to that task (no other action).
• closes WAVE-12 (also close/closed/fix/fixes/fixed/resolve/resolves/resolved) — marks the task done and moves it to the board's last column.
• WAVE-12 #time 2h — logs a time entry on the task (2h, 90m, 1:30, 1.5h).

Actions are attributed to the commit author (matched to a member by email), run once per commit, and only for commits authored after the repo was connected. Any message that contains the syntax triggers it — keep example directives out of real commit messages. Call the `guide` tool for the full reference.

REST API

The server is a thin wrapper over \/api/v1`(Bearertw_…` auth). Example:

curl -s http://localhost:3000/api/v1/tasks \
  -H "Authorization: Bearer tw_your_key"