@timewave-cloud/mcp

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"