@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.

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
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
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)

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"