weeek-mcp

Read-only MCP server for the Weeek Public API. Use it from Cursor or Claude Code to browse projects, search tasks, read attachments, and (with a browser session) load task comments.

Features

“Documents” here means task attachments, not Weeek Docs.

Related MCP server: Weeek MCP Server

Requirements

• Node.js ≥ 20

• Weeek API token (Workspace settings → API)

Install

git clone https://github.com/prod-broke-again/weeek-mcp.git
cd weeek-mcp
npm install
npm run build

Optional: refresh vendored OpenAPI with npm run fetch:openapi, then npm run generate:dto.

Configuration

Copy .env.example and set at least WEEEK_API_TOKEN. Never commit .env or session cookies.

Cursor / Claude Code

Example Cursor MCP config (~/.cursor/mcp.json or project .cursor/mcp.json):

{
  "mcpServers": {
    "weeek": {
      "command": "node",
      "args": ["/absolute/path/to/weeek-mcp/dist/bin/weeek-mcp.js"],
      "env": {
        "WEEEK_API_TOKEN": "your-token",
        "WEEEK_DEFAULT_PROJECT_ID": "2",
        "WEEEK_READ_ONLY_PROJECTS": "2"
      }
    }
  }
}

More examples: examples/mcp.cursor.json, examples/mcp.claude.json.

Tools

1. weeek_context — start here (sessionComments: ready|missing)

2. weeek_auth_status — session check + import instructions

3. weeek_session_import — paste session JSON

4. weeek_list_projects

5. weeek_get_project

6. weeek_get_board

7. weeek_search_tasks

8. weeek_my_tasks

9. weeek_get_task — card + comments when session is ready

10. weeek_get_task_comments — comments only

11. weeek_get_task_tree

12. weeek_read_attachment

13. weeek_list_members

14. weeek_list_tags

Typical flow: context → (auth_status / session_import if needed) → search_tasks → get_task → read_attachment.

Task comments (browser session)

Public API has no comments. The web app loads them from:

GET https://api.weeek.net/ws/{workspaceId}/tm/tasks/{taskId}?withSubtasks=1

with session cookies. weeek_session is HttpOnly, so document.cookie cannot see it.

Import once

1. Call weeek_auth_status (or open a task via weeek_get_task_comments).

2. In https://app.weeek.net → DevTools → Network → open any task.

3. Find api.weeek.net/ws/.../tm/tasks/... → Request Headers → Cookie → copy the value.

4. Console: paste the helper from weeek_auth_status, then run
   weeekExportSession("PASTE_COOKIE_HERE")
   (or pass workspace id as the second argument).

5. Paste the JSON into chat / call weeek_session_import.

Session is stored at ~/.weeek-mcp/session.json (Windows: %USERPROFILE%\.weeek-mcp\session.json).

Security: the cookie is a live login. Do not commit or share it. If leaked, log out of Weeek or rotate the password.

Development

npm test
npm run typecheck
npm run build
npm run dev   # stdio MCP via tsx

OpenAPI is vendored at openapi/weeek.json. Layout: domain → application → infrastructure → mcp.

License

MIT