Skip to main content
Glama
WEEEK MCP Server

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, 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 title and readOnlyHint / destructiveHint / idempotentHint / openWorldHint, so clients can auto-approve reads and gate destructive actions

  • Structured output — every tool declares an outputSchema and returns structuredContent (plus a JSON text block for older clients)

  • Current WEEEK Public API — task locations model (multi-project tasks), dedicated complete/un-complete, assignee, and comment endpoints

  • 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

Related MCP server: weeek-mcp

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

  2. 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 (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

weeek_get_current_user

Profile of the token owner. Use its id as assignee_id for "my tasks".

weeek_list_workspace_members

List workspace members (IDs for assignees, watchers, time entries).

weeek_list_projects

List projects in the workspace. Use FIRST to discover project IDs.

weeek_get_project

Get a single project's details, including project-level custom fields.

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, type, priority, tags, search, day) and sorting.

weeek_get_task

Full task details: description, locations, assignees, subtasks, time entries, custom fields.

weeek_list_task_comments

List comments on a task (Markdown).

weeek_list_tags

List workspace tags (IDs for task tags).

weeek_list_custom_fields

List global custom fields (IDs for task custom_fields).

Write tools

Tool

Purpose

weeek_create_task

Create a task in a project (optionally a column), with assignee, parent, type, priority, dates, tags.

weeek_update_task

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.

weeek_move_task

Place a task in a project/column (status change) or add it to another project.

weeek_remove_task_from_project ⚠️

Remove a task from one of its projects.

weeek_complete_task

Mark a task complete, or reopen it.

weeek_set_task_parent

Make a task a subtask of another, or detach it.

weeek_add_task_assignees / weeek_remove_task_assignees ⚠️

Manage task assignees.

weeek_add_task_watchers / weeek_remove_task_watchers ⚠️

Manage task watchers.

weeek_create_task_comment

Post a Markdown comment or reply on a task.

weeek_delete_task_comment ⚠️

Delete a task comment.

weeek_start_task_timer / weeek_stop_task_timer

Start or stop the time tracker on a task.

weeek_create_time_entry / weeek_update_time_entry

Log or edit time (minutes) on a task.

weeek_delete_time_entry ⚠️

Delete a time entry.

weeek_delete_task ⚠️

Delete a task.

weeek_set_task_mr_link

Write a merge/pull request URL into the task project's МР custom field (name overridable via field_name). weeek_move_task and weeek_complete_task also accept mr_url to do this in the same call.

Safety

  • Annotations over groups: every tool carries MCP annotations. Configure your client to auto-approve readOnlyHint tools and always confirm destructiveHint tools (⚠️ 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_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

Live 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.mjs

Use 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 tools
weeek_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_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

    A4.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and developer tools to interact programmatically with Yougile workspace, supporting project, task, user, board, and column management through natural language.
      16 npm
      19
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Local, 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.
      10
      58 npm
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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 npm
      MIT