@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

• In TimeWave, open the user menu → Account & API keys and create a key. Choose its permissions (scopes): read, tasks, timer — grant only what the agent needs (e.g. a read-only key). Copy the tw_… token (shown once). A key acts as you and can never do more than you can; tools whose scope the key lacks return a 403.
• Configure your MCP client with two env vars:
  • TIMEWAVE_API_URL — your instance (e.g. https://timewave.cloud)
  • TIMEWAVE_API_KEY — the tw_… token

The server is published to npm as @timewave-cloud/mcp, so npx fetches and runs it — nothing to clone or install. Needs Node 18+ (uses global fetch).

Claude Desktop config

Add to claude_desktop_config.json:

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

Restart the client; the timewave tools appear.

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",
        "TIMEWAVE_API_KEY": "tw_your_key_here"
      }
    }
  }
}

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

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"