WEEEK MCP Server

weeek-mcp-server

MCP (Model Context Protocol) server for the WEEEK task tracker. Gives AI coding agents (Claude Desktop, Cursor, Cline, and any other MCP client) direct read/write access to WEEEK projects, boards, tasks, and comments — no context switching.

Features

• 12 tools — 7 read (projects, boards, columns, tasks, comments) + 5 write (create/update/move/complete tasks, post comments)
• Read/write split — tools are grouped so MCP clients can auto-approve reads while gating writes
• Stdio transport — zero server infrastructure, runs via npx
• Token auth — single WEEEK_API_TOKEN env var, never logged
• Safe defaults — list tools paginate (default 20, max 50) so responses stay under the 25k token MCP limit
• Structured errors — API failures return isError: true with a human-readable message, the server never crashes

Installation

No installation needed — configure your MCP client to run it via npx.

Getting a WEEEK API Token

1. Sign in to WEEEK.
2. Open Workspace settings → API.
3. Generate a personal API token.
4. Treat it like a password — it grants full read/write access to your workspace. Rotate it if it leaks.

Configuration

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp-server"],
      "env": {
        "WEEEK_API_TOKEN": "your-weeek-token-here"
      }
    }
  }
}

Restart Claude Desktop.

Cursor

Edit ~/.cursor/mcp.json (or use Cursor Settings → MCP → Add new MCP server):

{
  "mcpServers": {
    "weeek": {
      "command": "npx",
      "args": ["-y", "weeek-mcp-server"],
      "env": {
        "WEEEK_API_TOKEN": "your-weeek-token-here"
      }
    }
  }
}

Generic MCP client

Any MCP client that supports stdio transport can launch:

command: npx
args: ["-y", "weeek-mcp-server"]
env: { WEEEK_API_TOKEN: "<your token>" }

NVM Workaround (IMPORTANT for nvm users)

If you installed Node via nvm, GUI applications (Claude Desktop, Cursor) do not source your shell startup files, so npx is not on their PATH. You will see spawn npx ENOENT in the client logs.

Fix: use the absolute path to your nvm npx binary.

1. In your terminal, run:

   which npx

Example output: /Users/you/.nvm/versions/node/v22.0.0/bin/npx

1. Put that absolute path in your MCP client config as the command:

   {
     "mcpServers": {
       "weeek": {
         "command": "/Users/you/.nvm/versions/node/v22.0.0/bin/npx",
         "args": ["-y", "weeek-mcp-server"],
         "env": {
           "WEEEK_API_TOKEN": "your-weeek-token-here"
         }
       }
     }
   }

This is the single most common setup failure across all npx-based MCP servers. If you upgrade Node via nvm, update the path.

Tools

All tools are prefixed weeek_. Read tools are side-effect free and safe for auto-approve. Write tools mutate WEEEK state and should prompt for user confirmation.

Read tools

| Tool | Purpose | |------|---------| | weeek_list_projects | List projects in the workspace. Use FIRST to discover project IDs. | | weeek_get_project | Get a single project's full details by ID. | | weeek_list_boards | List boards inside a project. | | weeek_list_board_columns | List columns (statuses) inside a board. Required before moving tasks. | | weeek_list_tasks | List tasks with filters (project, board, column, assignee, completion) and pagination. | | weeek_get_task | Get full details of a single task by ID. | | weeek_list_task_comments | List comments on a task. |

Write tools

| Tool | Purpose | |------|---------| | weeek_create_task | Create a NEW task. Requires title + project_id. | | weeek_update_task | Edit fields (title, description, priority, assignee, due date) of an existing task. | | weeek_move_task | Move a task to a different board column (status change). | | weeek_complete_task | Mark a task complete, or reopen a completed task. | | weeek_create_task_comment | Post a comment on a task. |

Safety

• Read/write separation: read tools and write tools are registered in separate groups. Configure your MCP client to auto-approve reads while gating writes.
• No delete operations: v1 intentionally does not expose delete endpoints — too destructive for an AI agent.
• Pagination defaults: list tools default to 20 results (max 50) to stay under the 25,000 token MCP response cap.
• Token handling: WEEEK_API_TOKEN is read from the env block only. It is never logged, echoed, or included in error messages.

Troubleshooting

| Symptom | Fix | |---------|-----| | spawn npx ENOENT in client logs | You are using nvm — see the NVM Workaround section above. | | WEEEK_API_TOKEN environment variable is required | The env block is missing or empty in your MCP client config. | | Invalid WEEEK_API_TOKEN | Token is wrong, revoked, or expired — regenerate in WEEEK workspace settings. | | Server disconnects immediately after starting | You are on Node < 20. Upgrade Node (nvm install 20) and update your config path. | | Tool returns "Resource not found (404)" | The ID doesn't exist in the workspace — list the parent resource first (e.g., weeek_list_projects before weeek_get_project). |

Development

git clone <this-repo>
cd weeek-mcp-server
npm install
npm run build
npm test

Scripts:

• npm run build — compile TypeScript to dist/
• npm run dev — run from source via tsx
• npm run lint — ESLint (enforces no-console rule for stdio safety)
• npm run typecheck — tsc --noEmit
• npm test — vitest unit tests

To smoke-test the built binary:

npm run build
WEEEK_API_TOKEN=test node dist/index.js
# server blocks on stdin — press Ctrl+C to exit

Requirements

• Node.js >= 20.0.0
• A WEEEK account with API access

License

MIT — see LICENSE.