WEEEK (smart)

weeek-mcp-smart

[npm version] [npm downloads] [CI] [node] [license] [IlyaIvanchikov/weeek-mcp MCP server]

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

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.

Install (Claude Code / Cursor)

claude mcp add weeek -s user -- npx -y weeek-mcp-smart# then set WEEEK_API_TOKEN in the generated config

Install (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

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_file only 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. Set WEEEK_ATTACH_DIR to point the jail somewhere specific or lock it down further. No special folder is required.
• weeek_delete_task is permanent and requires an explicit confirm: true; to merely close a task use weeek_complete_task.
• weeek_get_attachment returns 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's service is weeek; 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 to https, with no credentials on either hop. Non-images return metadata only, and anything over WEEEK_ATTACH_MAX_BYTES is 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: true and 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.

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 CRMWEEEK_TOOLSETS=all npx -y weeek-mcp-smart         # everything

Development

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.netnpx vitest run tests/contract.test.ts

A 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

Ilya Ivanchikov — GitHub · LinkedIn · Telegram · Channel