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:

   hljs language-bash

   Copy

   which npx
   

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

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

   hljs language-json

   Copy

   {
     "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

Write tools

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

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.