weeek-mcp
Summary: weeek-mcp is an MCP server that exposes Weeek task-management tools over its public REST API (the README also describes knowledge-base tools/resources that do not appear in this schema).
Discover context:
weeek_whoami,weeek_list_members,weeek_list_projects,weeek_list_boards,weeek_list_board_columnsto get ids for assignments and navigation.Read & search tasks:
weeek_list_taskswith filters (project, board, column, assignee, dates, tags, priority, type, completed, text search) andweeek_get_task.Manage the task lifecycle: create, update, complete, uncomplete, delete, and move tasks between board columns or boards.
People & hierarchy: set/remove assignees and watchers, nest or detach a task under a parent, add/remove a task from projects (tasks can live in several).
Time tracking: start/stop a running timer and create, update, or delete logged time entries (duration, date, user, overtime).
Attachments: upload local files to a task and fetch an attachment's metadata and download URL.
Fields & comments: list custom fields for a project, set custom field values (by name or id, with select/multiselect support), and list/add/update/delete task comments (comments go through Weeek's web API and need a KB login session).
Descriptions: HTML on create; Markdown on update, which writes via Weeek's collaborative editor channel and needs the KB session.
Workspace admin: action-based tools for tags, projects, boards, board columns, portfolios, and custom fields (create/update/delete/move/transfer/archive and select-option management).
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 create a task called 'Finish presentation' in the Marketing board"
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
Language: English · Русский
An MCP server for Weeek: manage tasks through the public REST API and browse the knowledge base through Weeek's internal API, exposed as MCP Resources so you can search and select KB documents as content (not links) from your MCP client.
Contents
Related MCP server: weeek-mcp
Features
Tasks and boards
Public REST API — projects, boards, board columns, and the full task lifecycle: create, update, complete, move between columns, assign and unassign members.
Knowledge base
Full CRUD. Weeek has no public KB API, so the server calls Weeek's internal JSON API (api.weeek.net/ws/{id}/kb/...) using cookies from a saved browser login. Documents are rendered to Markdown and published as MCP Resources (weeek-kb://<id>). Read/list/search/create/rename/delete go over the JSON API; in-place body editing speaks Weeek's collaborative protocol directly (Hocuspocus/Yjs), because bodies live in a shared document the REST API only serves a snapshot of. Content is converted between Markdown and Weeek's ProseMirror format automatically.
Capability-aware
Task tools appear when an API token is set; KB tools and resources appear when login credentials or a cached session are present.
Installation
Claude Desktop
Download
weeek-mcp.mcpbfrom the latest release.Open it (or drag it onto Settings → Extensions) and enter your Weeek API token: Weeek → Settings → API.
That's all for tasks. Desktop runs the server with its own uv, so you don't need Python.
For the knowledge base, sign in once from a terminal. This step needs uv:
uvx --from "weeek-mcp[kb]" playwright install chromium
uvx --from "weeek-mcp[kb]" weeek-mcp-loginA browser opens: sign in to Weeek and the session is saved. Then switch the extension off and on in Settings → Extensions.
Email and password in the extension settings are optional. With them the server signs in again by itself when the session expires. Without them, or if you use 2FA or SSO, run weeek-mcp-login again.
Other MCP clients
weeek-mcp is a plain stdio server, so it works with any MCP client that launches servers as a local subprocess: Claude Code, Cursor, Windsurf, Cline, Continue, Zed, VS Code (Copilot agent mode), Gemini CLI, Goose, LibreChat, and others, plus your own agents built on an MCP SDK. It needs Python 3.10+:
pip install "weeek-mcp[kb]" # drop [kb] if you only need tasks
playwright install chromium # knowledge base only
weeek-mcp-login # knowledge base only, one-time sign-inIf weeek-mcp-login or weeek-mcp isn't found, pip put them outside your PATH: add the scripts directory from pip show -f weeek-mcp to it, or use the absolute path in your client config.
Then register the weeek-mcp command with your client. Claude Code (-s user makes it available in every project):
claude mcp add weeek -s user -e WEEEK_API_TOKEN=... -- weeek-mcpCursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project):
{
"mcpServers": {
"weeek": {
"command": "weeek-mcp",
"env": { "WEEEK_API_TOKEN": "..." }
}
}
}VS Code (.vscode/mcp.json) uses a servers key and an explicit type:
{
"servers": {
"weeek": {
"type": "stdio",
"command": "weeek-mcp",
"env": { "WEEEK_API_TOKEN": "..." }
}
}
}On the knowledge base: task tools and
weeek_kb_*are ordinary MCP tools and work almost everywhere. Pulling documents in through an attachment menu relies on MCP Resources, which fewer clients surface. Where they aren't supported, read the KB withweeek_kb_read/weeek_kb_search— the content still lands in context. MCP and resources support moves fast per client; check the client's docs before relying on it.
Configuration
Environment variables (or a .env file, see .env.example). Only WEEEK_API_TOKEN is required, and only for task tools.
Variable | Purpose |
| Task API token. Required for task tools. |
| First automated KB login. Optional (skip if 2FA/SSO — use |
| KB workspace id. Optional — auto-detected via |
| Where the browser session is cached (defaults under |
|
|
| Seconds to cache the KB document list (default |
|
|
Tools
Tasks
Group | Tools |
Reading & navigation |
|
Task lifecycle |
|
Assignees, watchers, hierarchy |
|
Time & attachments |
|
Fields & comments |
|
Workspace admin
weeek_manage_tags, weeek_manage_projects, weeek_manage_boards, weeek_manage_board_columns, weeek_manage_portfolios, weeek_manage_custom_fields.
These take an action (create/update/delete/…) rather than one tool per operation — the CRUD is regular and the tool list stays readable. Custom fields live per board, per project or workspace-wide, so that tool takes a scope (global/project/board) plus scope_id.
Knowledge base
Group | Tools |
Reading |
|
Writing |
|
Structure |
|
Formatting |
|
weeek_kb_updatewith new content writes into the document's shared Yjs document over Weeek's collaborative websocket, because that — not REST — is where bodies are saved. No browser is involved and the document id is preserved.
Behavior
Priorities. Take either Weeek's number or its label:
Number | Label |
| low (Низкий) |
| medium (Средний) |
| high (Высокий) |
| hold (Замороженный) |
Custom fields. Set with custom_fields: on an existing task by field name or id ({"Ссылка на фичу": "https://…"}, null clears a field, a select takes the option name or id), on weeek_create_task by id only — weeek_list_custom_fields lists them. A field belongs to the projects it was added to, and Weeek stores nothing when you write to one it doesn't cover, so the write is verified and reported.
Descriptions. Editable on an existing task: weeek_update_task takes description as Markdown (empty string clears it). Weeek's REST API only accepts a description on create — PUT /tm/tasks/{id} has no such field — because descriptions sync through the same collaborative channel as KB document bodies, so this writes into that channel and needs the knowledge base session. weeek_create_task still takes its description as HTML, which is what that endpoint stores.
Comments. Read with weeek_list_task_comments, written with weeek_add_task_comment and rewritten in place with weeek_update_task_comment (all Markdown) — an edited comment beats posting a correction under the original. weeek_delete_task_comment removes one for good; Weeek keeps no trash for comments. Weeek's public API has no comments at all, so these go through its web API on the knowledge base session; no browser is launched, only the saved cookies.
Tables. One size to set: the pixel width of each column (minimum 90). New tables are fitted to the document's content column (~676px) instead of Weeek's 180px-per-column default, and existing widths are carried across a weeek_kb_update — a table that gains or loses a column is re-fitted. weeek_kb_table_widths sets them explicitly: widths: [300, 200, 176] for exact sizes, or fit: true to spread a table across the content column.
Attachments. weeek_kb_attach uploads local files and adds each one as a block at the end of the document: an image block for images, a file block with name and size for anything else. It leaves the rest of the body alone. Weeek keeps no attachment list beside a document, so the block is the attachment. weeek_kb_read shows it as a link on a line of its own, and weeek_kb_update keeps the block as long as that line stays in the new body; drop the line and the block goes with it.
Icons. Pass icon to weeek_kb_create/weeek_kb_update as a single emoji (🚀) or as one of Weeek's built-in icon names (weeek_kb_icons lists them); an empty icon removes it. Listings report the icon a document currently has.
Order and folders. A folder in Weeek is a document that has children, so weeek_kb_move moves and reorders both. Pass exactly one of parent_id, before or after. With parent_id the document becomes the first child of that document. With before or after it lands right next to that document, under the same parent, which may be the top level. To make a document the last one in a folder, pass after with the folder's current last child. A document created with parent_id goes to the end of that folder. A document in the trash cannot be a destination.
weeek_kb_reorder sets the order of a folder in one call. order lists ids that share a parent; those documents go to the start of the folder in that order, and the siblings you left out follow in their current order. weeek_kb_list returns documents depth-first in sidebar order, each with its parent_id. Pass parent_id to get only the direct children of one document, or "" for the top level.
When a folder is moved, Weeek reverses the order of everything inside it, and drag-and-drop in the web app does the same. weeek_kb_move and weeek_kb_reorder check for this and restore the original order.
Knowledge base in Claude context
Each KB document is published as an MCP Resource (weeek-kb://<id>). In Claude
Desktop you add them from the attachment (+) menu of the connected server — browse
the list or narrow it with weeek_kb_search — and the client pulls in the document
content, not a link.
Note on Project Context: Claude Desktop surfaces MCP resources as attachments. Whether a selected resource persists inside a Project's Context panel (vs. a single conversation) depends on your Claude Desktop version. The content-not-a-link behavior works regardless.
Status & limitations
Task tools follow Weeek's published OpenAPI spec.
Knowledge base uses Weeek's internal, undocumented API (
/ws/{id}/kb/...). It is not covered by any stability guarantee and may change without notice; if KB calls start failing, the endpoints inweeek_mcp/kb/client.pyare the place to look. Login automation targets Weeek's two-step web form (weeek_mcp/kb/session.py); accounts with 2FA/captcha/SSO should seed the session withweeek-mcp-logininstead.Document content is ProseMirror/TipTap JSON, converted to/from Markdown by
weeek_mcp/kb/prosemirror.py. Editing an existing body goes through Weeek's collaborative channel (there is no REST content-write):weeek_mcp/kb/collab.pyspeaks the Hocuspocus protocol, authenticates with a per-socket ticket, and replaces theprosemirrorfragment of the document's Y.Doc. Authoring covers the common Markdown subset (headings, paragraphs, lists, bold/inline code, code blocks, quotes, rules); rich cases like nested lists and tables are simplified.Table column widths live on the
table_bodynode, as a JSON string, and are written with the body rather than after it (weeek_mcp/kb/tables.py). Cell colors and per-column colors are stored alongside the widths but are not exposed as tools yet.
Development
See CONTRIBUTING.md for setup, tests, and pull requests.
License
This project is licensed under the MIT License — see LICENSE.
Available Tools
35 toolsweeek_add_task_commentA
Comment on a task. The text is Markdown (paragraphs, lists, bold/italic/code, links) and posts as you. Weeek's public API has no comments, so this drives its web API through the browser session — it needs WEEEK_EMAIL/WEEEK_PASSWORD or a cached login.
Inputs: text (required), task_id (required).
weeek_add_task_to_projectB
Put a task into a project (a task can live in several). Optionally target a board column there.
Inputs: task_id (required), project_id (required), board_column_id.
weeek_complete_taskC
Mark a task complete.
Inputs: task_id (required).
weeek_create_taskA
Create a task. Requires a project_id (and normally a board_column_id, which you get from weeek_list_board_columns). Dates are set separately via weeek_update_task.
Inputs: title (required), project_id (required), day, type, +6 more.
weeek_delete_taskC
Delete a task by id.
Inputs: task_id (required).
weeek_delete_task_commentA
Delete a comment for good — Weeek keeps no trash for these. To fix wording, prefer weeek_update_task_comment. comment_id comes from weeek_list_task_comments.
Inputs: task_id (required), comment_id (required).
weeek_get_attachmentC
Get one attachment's metadata and download URL by file id.
Inputs: file_id (required).
weeek_get_taskC
Get one task by id.
Inputs: task_id (required).
weeek_list_board_columnsC
List board columns (statuses) for a board. board_id is required by the Weeek API.
Inputs: board_id (required).
weeek_list_boardsB
List boards of a project.
Inputs: project_id (required).
weeek_list_custom_fieldsA
List the task custom fields visible in a project (id, name, type, select options). Weeek's public API exposes no schema endpoint for them, so this reads the fields off one of the project's tasks — a project with no tasks yet returns nothing. Tasks list every field of the workspace, so some of them may belong to other projects; writing to one of those is reported as an error.
Inputs: project_id (required).
weeek_list_membersB
List workspace members (id, name, email) — use their ids as assignees.
Inputs: no named parameters.
weeek_list_projectsA
List all task-manager projects (id, name).
Inputs: no named parameters.
weeek_list_task_commentsB
List a task's comments, oldest first, with their author and text.
Inputs: task_id (required).
weeek_list_tasksB
List tasks with optional filters (project, board, column, assignee, completion, tags, text search).
Inputs: day, tags, type, offset, +10 more.
weeek_manage_board_columnsB
Create, rename, delete or reorder a board column (status). Use weeek_list_board_columns to read them.
Inputs: action (required), name, board_id, board_column_id, +1 more.
weeek_manage_boardsA
Create, rename, delete or reorder a board. Use weeek_list_boards to read them.
Inputs: action (required), name, board_id, project_id, +1 more.
weeek_manage_custom_fieldsA
Create, update, delete, move or transfer custom fields and their select options. A field belongs to one board, one project, or the whole task manager (scope global) — set scope and scope_id accordingly. weeek_list_custom_fields reads the fields a project's tasks actually show.
Inputs: action (required), name, type, after, +9 more.
weeek_manage_portfoliosB
List, create, rename or delete portfolios (the folders projects live in).
Inputs: action (required), name, limit, offset, +3 more.
weeek_manage_projectsB
Create, update, delete, archive or unarchive a project. Use weeek_list_projects to read them.
Inputs: action (required), name, color, is_private, +3 more.
weeek_manage_tagsB
Workspace tags: list them (with ids to use in weeek_update_task), create, rename/recolor, or delete one.
Inputs: action (required), color, title, tag_id.
weeek_manage_time_entryB
Log time on a task, or edit/delete a logged entry. create and update need user_id, date, duration; delete needs entry_id.
Inputs: action (required), task_id (required), date, user_id, +3 more.
weeek_move_taskB
Move a task to a board column (status) and/or to another board. Give at least one of board_column_id, board_id.
Inputs: task_id (required), board_id, board_column_id.
weeek_remove_assigneesC
Remove assignees from a task.
Inputs: task_id (required), assignees (required).
weeek_remove_task_from_projectB
Remove a task from one of the projects it belongs to.
Inputs: task_id (required), project_id (required).
weeek_remove_watchersC
Remove watchers from a task.
Inputs: task_id (required), watchers (required).
weeek_set_assigneesC
Add assignees to a task (member ids from weeek_list_members).
Inputs: task_id (required), assignees (required).
weeek_set_task_parentA
Nest a task under another one, or detach it with parent_id null. after/before place it among its new siblings.
Inputs: task_id (required), parent_id (required), after, before.
weeek_set_watchersC
Add watchers (subscribers) to a task — member ids from weeek_list_members.
Inputs: task_id (required), watchers (required).
weeek_task_timerC
Start or stop the running timer on a task.
Inputs: action (required), task_id (required).
weeek_uncomplete_taskB
Mark a completed task as not complete.
Inputs: task_id (required).
weeek_update_taskC
Update a task's fields (title, priority, type, dates, duration, tags), its custom field values, and its description.
Inputs: task_id (required), tags, type, title, +8 more.
weeek_update_task_commentA
Rewrite one of your comments (Markdown), keeping it in place instead of posting a correction after it. comment_id comes from weeek_list_task_comments.
Inputs: text (required), task_id (required), comment_id (required).
weeek_upload_attachmentB
Attach local files to a task. Paths must exist on this machine.
Inputs: paths (required), task_id (required).
weeek_whoamiA
Return the current user (id, name) for the API token. Useful to get your userId for assignments.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 35 tools
Most tools have clearly distinct purposes with detailed descriptions that cross-reference related tools. A few pairs could be confused (e.g., move_task vs add_task_to_project, manage_time_entry vs task_timer), but the descriptions generally clarify the boundaries.
All tool names use a consistent snake_case with the weeek_ prefix and mostly follow a verb_noun pattern (list_, manage_, get_, create_, update_, delete_, add_, remove_, set_, move_, etc.). Minor deviations like 'whoami' and 'task_timer' break the pattern, and 'manage_' is used for multi-action tools, but overall the convention is predictable.
With 35 tools, the surface is heavy for a single MCP server, exceeding the typical 3-15 range. However, the breadth of the task management domain (projects, tasks, boards, columns, comments, custom fields, tags, time tracking, attachments, members, assignments, portfolios) justifies many of them, though some consolidation could still reduce the count.
The tool set covers core CRUD and lifecycle operations for most entities: projects, tasks, boards, columns, comments, custom fields, tags, time entries, attachments, assignees, watchers, and portfolios. Notable gaps include no list operation for time entries or attachments (only create/get), and no direct read of a single project or board, but these are minor and workable around.
Maintenance
Related MCP Connectors
Unofficial community ClickUp MCP via personal API token. Not affiliated with ClickUp.
Tasks, lists, docs, goals and time tracking for teams. Full API as MCP tools.
Read and edit your Tasks boards: create and update tasks, comment, and track time.
Search and manage your team's knowledge from MCP clients.
Related MCP Servers
- AlicenseCqualityDmaintenanceMCP server for WEEEK Public API v1 enabling management of tasks, projects, boards, tags, custom fields, time tracking, and CRM entities.1002MIT
- AlicenseNot gradedqualityCmaintenanceRead-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.MIT
- AlicenseBqualityCmaintenanceEnables MCP clients to manage Super Productivity tasks, projects, and tags via its Local REST API, including task creation, updates, starting, stopping, archiving, and reading status and Focus Mode state.16MIT
- AlicenseAqualityCmaintenanceEnables MCP clients to navigate and modify Weeek projects, boards, tasks, assignees, comments, tags, and time tracking through the Weeek API, with actions attributed to the API token owner.13MIT