weeek-mcp-smart
Summary: A one-click WEEEK MCP server (default tasks toolset + weeek_version) that takes names, not IDs, so a task can be created in a single call.
Discover the workspace: list projects, boards, columns, members, and tasks (server-side filters for project, board, column, assignee, completion, free-text search, priority, type, day or date range; paging with
allPages).Read one task: assignees, watchers, parent/subtasks, priority, dates, tags, locations, time entries, attachments, and custom-field values with option names.
Create tasks:
weeek_create_taskwith project/column/assignee by name or id, natural-languagedue, priority, type, parent subtask, andfieldsby field name;weeek_create_tasksbatches up to 50 with a per-item report.Update tasks: title, natural-language
due/start, priority, type, duration, tags (replace/clear), and custom-field values by name (note: description is not updatable — set on create).Organize: move a task to a column on a board, complete/reopen it, set or clear its parent, and add/remove it from additional projects.
Collaborate: list, add (markdown, threaded via
reply_to) and delete comments; add/remove assignees and watchers by member name or id.Files: attach a local file (only from the allowed directory/subfolders) and read WEEEK-hosted image attachments so screenshot-only tasks can be interpreted.
Safety rails: every delete/remove/detach action (task, comment, assignees, watchers, project membership) requires
confirm: trueand is annotated destructive.Extensible: opt in via
WEEEK_TOOLSETStotime,projects,custom-fields,crm(deals, funnels, statuses, organizations, contacts, details) orall;weeek_versionis always available.
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-smart add task "fix login bug" in project "Dev" assignee "Max" due tomorrow"
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-smart
The only one-click WEEEK MCP server — it takes names, not IDs. Create a task in one call:
weeek_create_task({ title: "Ship v1", project: "Marketing",
column: "In Progress", assignee: "Ilya", due: "next friday",
fields: { "Estimate": 5 } })Then weeek_add_comment, weeek_add_assignees, weeek_set_task_parent — all by name, all one call, custom fields included — and the CRM: weeek_create_deal({ status: "New", funnel: "Sales", title: "Big one", contacts: ["Ann Lee"] }).
No list_projects → list_boards → list_columns → list_members dance first.
Where it is published
Where | Link |
npm | |
Official MCP registry |
|
Glama | |
GitHub Releases | latest release, with the one-click |
Every v* tag publishes to npm, the MCP registry and GitHub Releases in one CI run; Glama re-indexes the repository on its own schedule.
Related MCP server: weeek-mcp
Install (Claude Code / Cursor)
claude mcp add weeek -s user -- npx -y weeek-mcp-smart
# then set WEEEK_API_TOKEN in the generated configInstall (Claude Desktop, one click)
⬇ Download the latest .mcpb, then open it in Claude Desktop (Settings → Extensions → install from file). You'll be prompted for your WEEEK API token — it's stored in your OS keychain.
All releases: https://github.com/IlyaIvanchikov/weeek-mcp/releases
Get a token
WEEEK → Settings → API → generate a personal token.
Configuration
Env var | Required | Default | Purpose |
| to call tools | — | Your WEEEK personal API token. The server starts and lists its tools without it, but any tool call fails until it is set. |
| no |
| Override for self-hosted / regional hosts. |
| no |
| Per-request timeout. |
| no |
| Comma-separated groups of tools to expose, or |
| no | the server's working directory | Directory |
| no |
| Max attachable file size. |
Safety
This server is driven by an LLM that can read untrusted content (task text, web pages), so the two riskiest tools are guarded:
weeek_attach_fileonly reads files inside an allowed directory (its subfolders included). By default that's the server's working directory — so it works with no setup for local files, while paths outside it (/etc/passwd,~/.ssh,..traversal, symlinks that escape) are refused. SetWEEEK_ATTACH_DIRto point the jail somewhere specific or lock it down further. No special folder is required.weeek_delete_taskis permanent and requires an explicitconfirm: true; to merely close a task useweeek_complete_task.weeek_get_attachmentreturns the image for an attachment WEEEK hosts itself, so a task specified in screenshots can be read rather than guessed at. It downloads bytes only when the attachment'sserviceisweeek; an attachment parked in Google Drive/Dropbox/OneDrive/Box comes back as metadata with its URL instead. The download sends no token at all: WEEEK hands out a pre-signed one-hour URL that redirects to its storage bucket, and the server follows exactly one redirect, only tohttps, with no credentials on either hop. Non-images return metadata only, and anything overWEEEK_ATTACH_MAX_BYTESis refused rather than truncated.Every tool that deletes, archives or detaches — a project, board, column, tag, portfolio, comment, time entry, custom field or field option; a funnel, status, deal, organization or contact, a contact's or organization's address, email or phone; an assignee, watcher, contact, organization or tag link; a task's membership of a project — requires
confirm: trueand is marked destructive in its annotations, so a client can ask before running it.
Toolsets
Every tool's schema is sent to the model on every request, so the server exposes a small
default and lets you opt into more. Set WEEEK_TOOLSETS to a comma-separated list, or all.
Toolset | Tools | Default |
|
| yes |
|
| |
|
| |
|
| |
|
| |
| every toolset |
weeek_version is always available. The default is the task surface: 16 871 bytes of
tool schemas per request; crm alone is 32 290 bytes; all is 76 692 bytes. An unknown name is
rejected at startup with the list of valid ones. Every operation of WEEEK's public API (157) is
registered, and all but one reach a tool (PATCH /crm/deals/{id}: the API ignores most of its body,
so weeek_update_deal uses PUT and the link routes instead) — the registry is checked against the
vendored OpenAPI document in both directions on every test run.
Custom-field values need no extra toolset: weeek_get_task returns them, and
weeek_create_task / weeek_update_task take fields: { "Estimate": 5, "Stage": "Review" } by
field name (on create, global and project fields; a board's own fields once the task exists, via
weeek_update_task). The custom-fields toolset is for administering the fields themselves — in the
global scope, a project, a board or a CRM funnel. A board's fields are read off its tasks because
the API lists them nowhere else, so an empty board shows none.
The crm toolset takes every reference by name: a funnel, a status inside it, a deal by title
(with its funnel or status) or by id, organizations, contacts by full name, currencies by code,
tags by title. Deals carry custom-field values like tasks (fields by name; on
weeek_create_deal pass funnel too). Addresses, emails and phones belong to
organizations and contacts and are changed with weeek_add_detail / weeek_update_detail /
weeek_delete_detail.
Upgrading from 1.0.0: weeek_create_task / weeek_update_task due now actually sets the due date
(the key sent before was ignored by the API); weeek_update_deal now applies custom fields and the
four link lists, and lost description (the API only sets it on create);
weeek_create_organization / weeek_update_organization take one responsible instead of
responsibles (the list was ignored); weeek_list_deals lost sort: "amount" (the API answers 500);
weeek_update_project color must now be # and six hex digits; a 200 the API marks
success: false (e.g. a plan limit) is now reported as an error.
Upgrading from 0.7.0: no tool was renamed or removed; WEEEK_TOOLSETS=tasks is still the
default. Opt in with crm or all.
Upgrading from 0.5.0: the default toolset grew from 12 tools to 24 in 0.6.0 (plus weeek_version), and WEEEK_TOOLSETS=tasks is still the default, so nothing else changes unless you opt in to time, projects or all.
WEEEK_TOOLSETS=tasks,crm npx -y weeek-mcp-smart # add the CRM
WEEEK_TOOLSETS=all npx -y weeek-mcp-smart # everythingDevelopment
Updating the API spec snapshot
spec/weeek-openapi.json is a snapshot of WEEEK's public OpenAPI document. A test
(tests/contract.test.ts) checks that every operation the server calls exists in it and that
every operation the spec declares is registered — 157 both ways — so an API change
shows up as a failing test, not as a surprise in production.
It needs Node ≥ 18 (for fetch), and curl only when REFRESH_SPEC_INTERFACE is set.
npm run refresh-spec # re-extract from developers.weeek.net
npx vitest run tests/contract.test.tsA successful refresh prints one line such as
wrote …/spec/weeek-openapi.json: openapi 3.1.1, 99 paths, 157 operations, 35 schemas (from weeek.yaml-<hash>.js).
If the refresh fails with a DNS or connection error, read the comment at the top of
scripts/refresh-spec.mjs — it lists the known causes (VPN resolver, blocked tunnel) and the
exact fix for each.
Author
Available Tools
25 toolsweeek_add_assigneesA
Assign one or more workspace members (by name or id) to a WEEEK task, keeping the existing assignees. Returns the task.
Inputs: id (required), assignees (required).
weeek_add_commentA
Add a markdown comment to a WEEEK task as the token's owner. Pass reply_to (a comment id from weeek_list_comments) to answer in a thread.
Inputs: id (required), markdown (required), reply_to.
weeek_add_task_to_projectA
Show a WEEEK task in another project too (a task can live in several). Project and optional column by name or id. To move between boards of one project use weeek_move_task.
Inputs: id (required), project (required), column.
weeek_add_watchersA
Add members (by name or id) as watchers of a WEEEK task, so they get its notifications. Returns the task; watchers are its watchers field.
Inputs: id (required), watchers (required).
weeek_attach_fileA
Attach a local file to a WEEEK task. For safety only files inside the allowed directory (the server's working directory by default, or WEEEK_ATTACH_DIR if set) — and its subfolders — may be attached; paths outside it are refused.
Inputs: path (required), task_id (required).
weeek_complete_taskA
Mark a WEEEK task complete, or reopen it (completed:false).
Inputs: id (required), completed (required).
weeek_create_taskA
Create a WEEEK task. Accepts project/column/assignee by NAME or id, a natural-language due date, a priority (low, medium, high, hold), a type (action, meet, call), a parent task id for a subtask, and custom-field values in fields by field name (global and project fields). One call — no need to look up ids first. Omit assignee to self-assign; to change assignees later use weeek_add_assignees / weeek_remove_assignees.
Inputs: title (required), project (required), due, type, +6 more.
weeek_create_tasksA
Create up to 50 WEEEK tasks in one call. Each item takes the same fields as weeek_create_task: title and project (name or id) are required; column, assignee, due, description, priority, type, parent and fields are optional. Items are created in order and one bad name does not abort the batch: the reply is one entry per item, { ok: true, task } or { ok: false, error, candidates? }.
Inputs: tasks (required).
weeek_delete_commentADestructive
Permanently delete one comment from a WEEEK task. Irreversible; requires confirm:true.
Inputs: id (required), confirm (required), comment_id (required).
weeek_delete_taskADestructive
Permanently delete a WEEEK task by id. Irreversible — the task is removed, not just completed. Requires confirm:true; to merely close a task use weeek_complete_task instead.
Inputs: id (required), confirm (required).
weeek_get_attachmentA
Read one WEEEK attachment by id. For an image WEEEK hosts itself this returns the image, so a task whose requirements live in a screenshot can actually be read instead of guessed at from the surrounding text; anything else comes back as metadata. Ids come from a task's attachments list (weeek_get_task).
Inputs: id (required), metadataOnly.
weeek_get_taskA
Get one WEEEK task by id: assignees, watchers, parent and subtasks, priority, dates, tags, locations, time entries, attachments and custom-field values (customFields, option names shown).
Inputs: id (required).
weeek_list_boardsA
List the boards of a WEEEK project (by name or id): id, name, privacy. Use it to find a board for weeek_move_task or weeek_list_columns.
Inputs: project (required).
weeek_list_columnsA
List the columns of a WEEEK board: id, name, boardId. Pass the board by id, or by name together with its project.
Inputs: board (required), project.
weeek_list_commentsA
List the comments on a WEEEK task: id, author member id, markdown, reply parent, timestamps. Paged; hasMore says whether to call again with a larger offset.
Inputs: id (required), limit, offset.
weeek_list_membersA
List WEEEK workspace members (id + display name). Any tool that takes an assignee, watcher or member accepts these names directly; use this to see who exists.
Inputs: no named parameters.
weeek_list_projectsA
List WEEEK projects: id, name, isPrivate, status and portfolioId. Use weeek_get_project for a project's description and team.
Inputs: no named parameters.
weeek_list_tasksA
List WEEEK tasks with server-side filters: project, board, column, assignee (userId), completion, free-text search, priority, type, a single day or a startDate–endDate range (dd.mm.yyyy), completion dates. Set allPages=true together with userId, startDate, and endDate to fetch every matching page inside the connector without returning unrelated workspace pages.
Inputs: all, day, type, limit, +14 more.
weeek_move_taskA
Move a WEEEK task to a column (by name or id, scoped to the given board) on that board. Find board ids with weeek_list_boards.
Inputs: id (required), column (required), board_id (required).
weeek_remove_assigneesADestructive
Unassign one or more members (by name or id) from a WEEEK task. Requires confirm:true. Returns the task.
Inputs: id (required), confirm (required), assignees (required).
weeek_remove_task_from_projectADestructive
Remove a WEEEK task from one of its projects (by name or id); the task keeps its other projects. Requires confirm:true.
Inputs: id (required), confirm (required), project (required).
weeek_remove_watchersADestructive
Stop members (by name or id) watching a WEEEK task. Requires confirm:true. Returns the task.
Inputs: id (required), confirm (required), watchers (required).
weeek_set_task_parentA
Make a WEEEK task a subtask of parent (a task id), or pass parent:null to detach it and make it top-level again.
Inputs: id (required), parent (required).
weeek_update_taskA
Update a WEEEK task: title, natural-language due and start dates (start goes with the due date — due or the task's own — because the API refuses one alone; some plans refuse start dates), priority (low, medium, high, hold), type (action, meet, call), duration in minutes, tags by name or id (replaces; an empty list clears), and fields: custom-field values by field name (options and members by name; null clears; other fields keep their values). Description is NOT updatable — the API ignores it; set it on create. Assignees, watchers, parent and projects have their own tools.
Inputs: id (required), due, tags, type, +5 more.
weeek_versionA
Return this MCP server's name and version, so callers can check which build is running.
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 25 tools
Boundaries are explicitly drawn: update_task covers title/dates/priority/tags/fields while assignees, watchers, parent and projects each get dedicated tools, and descriptions call this out. Single (create_task) vs batch (create_tasks), read vs write for attachments, and move_task vs add_task_to_project are all clearly distinguished. No two tools appear to do the same thing.
Every tool uses the same weeek_ prefix with a strict verb_noun snake_case pattern (list_boards, create_task, remove_assignees, add_comment). The only nominal outlier, weeek_version, is a harmless domain-standard convention. Highly predictable across all 25 tools.
At 25 tools this is at the heavy edge, but the domain (tasks, subtasks, projects, boards, columns, members, assignees, watchers, comments, attachments) legitimately justifies the scope. Each add/remove pair and lifecycle operation earns its place rather than being redundant. Slightly over the comfortable 3-15 range but defensible.
Strong lifecycle coverage: task CRUD, batch create, complete/reopen, move, subtask parenting, comment list/add/delete, attachment read/write, plus projects, boards, columns and members. Minor gaps exist (no comment edit, no attachment removal, no project/board creation) and description updates are impossible via the API, but these are documented and core workflows are covered.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Headless task management for bots, apps and AI agents. Remote MCP server, OAuth or access token.
Toggl 2.0 MCP server for tasks, projects, time entries, and workspace operations.
MCP server for Getfly CRM — customers, opportunities, orders, tickets and tasks.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceFull-featured MCP server integrating all 71 endpoints of the Weeek API as MCP tools for AI clients, enabling task, project, and workspace management via natural language.2-
- 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
- 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