WEEEK MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@WEEEK MCP Server list my projects"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, comments, assignees, and time tracking — no context switching.
Features
30 tools — 11 read + 19 write covering projects, boards, columns, tasks, comments, assignees, watchers, subtasks, multi-project locations, timers, time entries, tags, custom fields, and MR links
MCP tool annotations — every tool has a
titleandreadOnlyHint/destructiveHint/idempotentHint/openWorldHint, so clients can auto-approve reads and gate destructive actionsStructured output — every tool declares an
outputSchemaand returnsstructuredContent(plus a JSON text block for older clients)Current WEEEK Public API — task
locationsmodel (multi-project tasks), dedicated complete/un-complete, assignee, and comment endpointsStdio transport — zero server infrastructure, runs via
npxToken auth — single
WEEEK_API_TOKENenv var, never loggedSafe defaults — list tools paginate (default 20, max 50) so responses stay under the 25k token MCP limit
Structured errors — API failures return
isError: truewith a human-readable message, the server never crashes
Related MCP server: weeek-mcp
Installation
No installation needed — configure your MCP client to run it via npx.
Getting a WEEEK API Token
Sign in to WEEEK.
Open Workspace settings → API.
Generate a personal API token.
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.
In your terminal, run:
which npxExample output:
/Users/you/.nvm/versions/node/v22.0.0/bin/npxPut 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 (readOnlyHint: true) and safe for auto-approve. Write tools mutate WEEEK state; tools marked ⚠️ are destructive (destructiveHint: true) and should always require confirmation.
Read tools
Tool | Purpose |
| Profile of the token owner. Use its |
| List workspace members (IDs for assignees, watchers, time entries). |
| List projects in the workspace. Use FIRST to discover project IDs. |
| Get a single project's details, including project-level custom fields. |
| List boards inside a project. |
| List columns (statuses) inside a board. Required before moving tasks. |
| List tasks with filters (project, board, column, assignee, completion, type, priority, tags, search, day) and sorting. |
| Full task details: description, locations, assignees, subtasks, time entries, custom fields. |
| List comments on a task (Markdown). |
| List workspace tags (IDs for task |
| List global custom fields (IDs for task |
Write tools
Tool | Purpose |
| Create a task in a project (optionally a column), with assignee, parent, type, priority, dates, tags. |
| Edit title, priority, type, start/due date(time), duration, tags, custom fields. Description can only be set at creation — the WEEEK API ignores it on update. |
| Place a task in a project/column (status change) or add it to another project. |
| Remove a task from one of its projects. |
| Mark a task complete, or reopen it. |
| Make a task a subtask of another, or detach it. |
| Manage task assignees. |
| Manage task watchers. |
| Post a Markdown comment or reply on a task. |
| Delete a task comment. |
| Start or stop the time tracker on a task. |
| Log or edit time (minutes) on a task. |
| Delete a time entry. |
| Delete a task. |
| Write a merge/pull request URL into the task project's |
Safety
Annotations over groups: every tool carries MCP annotations. Configure your client to auto-approve
readOnlyHinttools and always confirmdestructiveHinttools (⚠️ above).Destructive operations exist since 0.2.0: deletes and removals are exposed but explicitly marked destructive. If you don't want an agent to have them, deny those tools in your MCP client.
Pagination defaults: list tools default to 20 results (max 50) to stay under the 25,000 token MCP response cap.
Token handling:
WEEEK_API_TOKENis read from theenvblock only. It is never logged, echoed, or included in error messages.
Troubleshooting
Symptom | Fix |
| You are using nvm — see the NVM Workaround section above. |
| The |
| Token is wrong, revoked, or expired — regenerate in WEEEK workspace settings. |
Server disconnects immediately after starting | You are on Node < 20. Upgrade Node ( |
Tool returns "Resource not found (404)" | The ID doesn't exist in the workspace — list the parent resource first (e.g., |
Development
git clone <this-repo>
cd weeek-mcp-server
npm install
npm run build
npm testScripts:
npm run build— compile TypeScript todist/npm run dev— run from source viatsxnpm run lint— ESLint (enforces no-console rule for stdio safety)npm run typecheck—tsc --noEmitnpm 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 exitLive end-to-end test against the real WEEEK API (drives dist/index.js over stdio, creates [mcp-smoke] tasks in the given project and deletes them afterwards):
npm run build
WEEEK_API_TOKEN=<token> node scripts/live-smoke.mjs # lists projects to pick an id
WEEEK_API_TOKEN=<token> WEEEK_SMOKE_PROJECT_ID=<test project id> node scripts/live-smoke.mjsUse a dedicated test project with at least one board (2+ columns) and one workspace tag.
Requirements
Node.js >= 20.0.0
A WEEEK account with API access
License
MIT — see LICENSE.
Available Tools
12 toolsweeek_complete_taskA
Mark a WEEEK task as COMPLETE or REOPEN a completed task. WRITE OPERATION — the MCP client may prompt for confirmation. Required: task_id. Optional: completed (default true), mr_url (records a merge/pull request link on the "МР" custom field in the same call), field_name (only with mr_url). Pass completed=false to reopen. Returns the updated task. DISTINCT from weeek_move_task: completing a task is a done/undone toggle, independent of which column it lives in. DISTINCT from weeek_update_task: completion is not an editable field — it has its own dedicated semantics in WEEEK. Use this tool when the user says 'mark done', 'complete', 'finish', 'close', 'reopen', or 'uncomplete'. task_id must come from weeek_list_tasks.
Inputs: task_id (required), mr_url, completed, field_name.
weeek_create_taskA
Create a NEW task in WEEEK. WRITE OPERATION — the MCP client may prompt for user confirmation before this runs. Required: title and project_id. Optional: description, board_id, board_column_id (status), priority, assignee_id, due_date. Returns the created task object in the same shape as weeek_get_task. Use this ONLY when creating a brand-new task; to change an existing task's fields use weeek_update_task, to move it to a different column use weeek_move_task, to mark it done use weeek_complete_task. All *_id parameters must come from the corresponding list tools — do not guess IDs.
Inputs: title (required), project_id (required), board_id, date_end, +4 more.
weeek_get_projectA
Get full details of a specific WEEEK project by ID. Use this AFTER weeek_list_projects to drill into a project and see its description, creation date, and settings. Returns the full project object. For listing boards inside the project, use weeek_list_boards with this project's id. The project_id parameter must be obtained from weeek_list_projects (do not guess IDs).
Inputs: project_id (required).
weeek_get_taskA
Get full details of a single WEEEK task by ID. Use this AFTER weeek_list_tasks when an agent needs the complete task context — full description, priority, assignee, due date, board/column location, timestamps. The task_id must come from weeek_list_tasks — do not guess IDs.
Inputs: task_id (required).
weeek_list_board_columnsA
List columns (status buckets) of a specific WEEEK board. Use this AFTER weeek_list_boards to understand the statuses that exist on a board — e.g. 'Todo', 'In Progress', 'Done'. Columns are the task status mechanism in WEEEK; you MUST call this before weeek_move_task (Phase 3) to know which column_id to target. Returns array of {id, name, boardId, order}. The board_id parameter must come from weeek_list_boards — do not guess.
Inputs: board_id (required), limit, offset.
weeek_list_boardsA
List all boards inside a WEEEK project. Use this AFTER weeek_list_projects to discover kanban boards within a project. A board is a container of columns (statuses) and tasks. Returns array of {id, name, projectId, type}. To see the columns/statuses of a specific board, use weeek_list_board_columns next. The project_id parameter must come from weeek_list_projects — do not guess.
Inputs: project_id (required), limit, offset.
weeek_list_projectsA
List projects in the WEEEK workspace. Use this FIRST when an agent needs to discover what projects exist before drilling into boards or tasks. Returns an array of projects with id, name, parentId (for nested projects), and isArchived flag. For a specific project's full details, use weeek_get_project with the id returned here. For board discovery within a project, use weeek_list_boards next.
Inputs: limit, offset.
weeek_list_tasksA
List tasks in WEEEK with optional filters. This is the PRIMARY tool for 'what needs doing?' queries. Filter by project_id, board_id, column_id (status), assignee_id, or is_completed. Pagination is ENFORCED: default 20, max 50 per response, to stay under the 25k-token MCP response cap — call again with a higher offset if more are needed. Returns shaped tasks with id, title, projectId, boardId, boardColumnId, assigneeId, isCompleted, priority, dueDate. For full task description and details, use weeek_get_task with an id returned here. All *_id parameters must come from weeek_list_projects / weeek_list_boards / weeek_list_board_columns — do not guess IDs.
Inputs: limit, offset, board_id, column_id, +3 more.
weeek_list_workspace_membersA
List members (users) of the WEEEK workspace. Use this FIRST when an agent needs to resolve a person's name to a user ID — required before filtering tasks by assignee_id in weeek_list_tasks or setting assignee_id on weeek_create_task / weeek_update_task. Returns shaped members with id, name, email, role. Pagination ENFORCED: default 20, max 50 per response. The WEEEK workspace is determined by the API token.
Inputs: limit, offset.
weeek_move_taskA
Move a WEEEK task to a different board column. This IS how you change a task's status in WEEEK — columns ARE the status mechanism. WRITE OPERATION — the MCP client may prompt for confirmation. Required: task_id and board_column_id. Optional: board_id (only when moving across boards), mr_url (records a merge/pull request link on the "МР" custom field in the same call), field_name (only with mr_url). Returns the updated task. DISTINCT from weeek_update_task: use update for field edits (title, description, priority, assignee, due date); use move for column/status changes. DISTINCT from weeek_complete_task: use complete for the done/undone toggle even though 'completed' is visually similar to a 'Done' column. board_column_id must come from weeek_list_board_columns — do not guess.
Inputs: task_id (required), board_column_id (required), mr_url, board_id, +1 more.
weeek_set_task_mr_linkA
Attach a merge/pull request URL to a WEEEK task by writing it into the "МР" custom field. WRITE OPERATION — the MCP client may prompt for confirmation. Required: task_id, mr_url. Optional: field_name (defaults to "МР"). Call this right after opening an MR/PR for a task. The custom field must already exist on the task's project in WEEEK — this tool only writes to it, it does not create custom fields. To record the MR link at the same time as a status change, pass mr_url to weeek_move_task or weeek_complete_task instead. task_id must come from weeek_list_tasks.
Inputs: mr_url (required), task_id (required), field_name.
weeek_update_taskA
Update editable fields of an EXISTING task in WEEEK. WRITE OPERATION — the MCP client may prompt for confirmation. Required: task_id. Optional: title, description, priority, assignee_id, due_date — only provided fields are sent, omitted fields remain unchanged. Returns the updated task. Do NOT use this to move tasks between columns (use weeek_move_task) or to mark tasks complete (use weeek_complete_task) — those are separate operations in WEEEK. The task_id must come from weeek_list_tasks.
Inputs: task_id (required), title, date_end, priority, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct operation (complete, create, move, update, list, etc.) with explicit differentiation. Even similar tools like complete_task vs move_task vs update_task are clearly separated by descriptions and use cases.
All 12 tools follow the consistent pattern `weeek_<verb>_<noun>` using snake_case. Verbs (list, get, create, update, move, complete, set) are uniformly applied across the set.
12 tools is a well-scoped number for a task management server. It covers essential operations for tasks, projects, boards, columns, and members without unnecessary redundancy.
The tool surface is nearly complete for task management: create, read, update, move, complete, and link MRs. Minor gaps exist (no task deletion, no project/board/column creation or update), but core workflows are fully covered.
Maintenance
Related MCP Connectors
Open your team's project from the AI you use: read and write its brief, documents, tasks and notes.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
AI agents use CalmBoard MCP to access board data, tasks, insights, and project workflows.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI agents and developer tools to interact programmatically with Yougile workspace, supporting project, task, user, board, and column management through natural language.16 npm19MIT
- AlicenseAqualityCmaintenanceLocal, read-only-by-default MCP server for Weeek that connects AI clients to your workspace over stdio, enabling listing projects, tasks, boards, members, and tags with opt-in write tools for task management.1058 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code and OpenAI Codex to interact with the Weeek task tracker through natural language, covering task creation, searching, updating, moving, completing, commenting, and file attachments via thirteen curated tools.19 npmMIT
- AlicenseNot gradedqualityCmaintenanceEnables AI coding agents to securely read, update, and create tasks on ProjectFlow boards.MIT