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

• Features
• Installation
  • Claude Desktop
  • Other MCP clients
• Tools
• Knowledge base in Claude context
• Status & limitations
• Development
• License

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

1. Download weeek-mcp.mcpb from the latest release.
2. 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-login

A 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-in

If 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-mcp

Cursor (~/.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 with weeek_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.

Tools

Tasks

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

weeek_kb_update with 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:

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.

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 in weeek_mcp/kb/client.py are 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 with weeek-mcp-login instead.
• 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.py speaks the Hocuspocus protocol, authenticates with a per-socket ticket, and replaces the prosemirror fragment 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_body node, 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.