WEEEK (smart)

weeek-mcp-smart

唯一支持一键安装的 WEEEK MCP 服务——它接受的是名称，而不是 ID。只需一次调用即可创建任务：

weeek_create_task({ title: "Ship v1", project: "Marketing",
                    column: "In Progress", assignee: "Ilya", due: "next friday",
                    fields: { "Estimate": 5 } })

接着调用 weeek_add_comment、weeek_add_assignees、weeek_set_task_parent——所有操作都按名称执行，只需一次调用，还支持自定义字段；CRM 也一样：weeek_create_deal({ status: "New", funnel: "Sales", title: "Big one", contacts: ["Ann Lee"] })。

无需先依次执行 list_projects → list_boards → list_columns → list_members。

发布平台

平台	链接
npm	weeek-mcp-smart
官方 MCP 注册表	io.github.IlyaIvanchikov/weeek-mcp-smart (注册表)
Glama	glama.ai/mcp/servers/IlyaIvanchikov/weeek-mcp
GitHub Releases	最新版本，包含适用于 Claude Desktop 的一键安装包 weeek-mcp-smart.mcpb

每个 v* 标签都会在一次 CI 运行中发布到 npm、MCP 注册表和 GitHub Releases；Glama 则按自己的计划重新索引仓库。

安装（Claude Code / Cursor）

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

安装（Claude Desktop，一键安装）

⬇ 下载最新的 .mcpb，然后在 Claude Desktop 中打开（Settings → Extensions → install from file）。系统会提示你输入 WEEEK API 令牌，该令牌会存储在操作系统密钥链中。

所有版本：https://github.com/IlyaIvanchikov/weeek-mcp/releases

获取令牌

WEEEK → Settings → API → 生成个人令牌。

配置

环境变量	必需	默认值	用途
WEEEK_API_TOKEN	调用工具时必需	—	你的 WEEEK 个人 API 令牌。没有此令牌时，服务仍会启动并列出工具，但在设置令牌前，任何工具调用都会失败。
WEEEK_API_BASE_URL	否	https://api.weeek.net/public/v1	用于覆盖可自托管或区域性主机的地址。
WEEEK_TIMEOUT_MS	否	30000	单次请求超时时间。
WEEEK_TOOLSETS	否	tasks	要公开的逗号分隔工具组，或使用 all。参见 Toolsets。
WEEEK_ATTACH_DIR	否	服务的工作目录	weeek_attach_file 可读取的目录（参见 Safety）。
WEEEK_ATTACH_MAX_BYTES	否	10485760（10 MB）	可附加文件的最大大小。

安全性

此服务由大模型驱动，可读取不可信内容（任务文本、网页），因此风险最高的两种工具都有防护：

• weeek_attach_file 只能读取允许目录中的文件（包括其子文件夹）。默认情况下，该目录是服务的工作目录——因此无需设置即可处理本地文件，而目录之外的路径（/etc/passwd、~/.ssh、.. 路径遍历、逃逸的符号链接）都会被拒绝。设置 WEEEK_ATTACH_DIR 可将访问限制指向特定位置，或进一步收紧限制。无需专用文件夹。
• weeek_delete_task 会永久删除任务，并且需要明确设置 confirm: true；若只想关闭任务，请使用 weeek_complete_task。
• weeek_get_attachment 会返回 WEEEK 自行托管的附件图片，因此可以直接读取截图中指定的任务，而不必猜测。仅当附件的 service 为 weeek 时才会下载字节数据；存放在 Google Drive/Dropbox/OneDrive/Box 中的附件则会以元数据形式返回，并附带其 URL。下载时不会发送任何令牌：WEEEK 会提供一个有效期为 1 小时的预签名 URL，该 URL 会重定向到其存储桶，服务只会跟随一次重定向，且仅允许跳转到 https，两个请求环节都不会携带凭据。非图片附件只会返回元数据，超过 WEEEK_ATTACH_MAX_BYTES 的内容会被拒绝，而不会截断。
• 每个用于删除、归档或解除关联的工具——涉及项目、看板、列、标签、作品集、评论、工时记录、自定义字段或字段选项；漏斗、状态、交易、组织或联系人；联系人的地址、电子邮件或电话号码；负责人、关注者、联系人、组织或标签关联；任务与项目的关联——都需要设置 confirm: true，并在注解中标记为具有破坏性，以便客户端在执行前询问确认。

工具集

每次请求都会将每个工具的架构发送给模型，因此服务默认只公开少量工具，并允许你选择启用更多工具。将 WEEEK_TOOLSETS 设置为逗号分隔的列表，或设置为 all。

工具集	工具	默认
tasks	weeek_list_projects, weeek_list_boards, weeek_list_columns, weeek_list_tasks, weeek_get_task, weeek_list_members, weeek_get_attachment, weeek_create_task, weeek_create_tasks, weeek_update_task, weeek_move_task, weeek_complete_task, weeek_attach_file, weeek_delete_task, weeek_list_comments, weeek_add_comment, weeek_delete_comment, weeek_add_assignees, weeek_remove_assignees, weeek_add_watchers, weeek_remove_watchers, weeek_add_task_to_project, weeek_remove_task_from_project, weeek_set_task_parent	是
time	weeek_set_timer, weeek_add_time_entry, weeek_update_time_entry, weeek_delete_time_entry
projects	weeek_get_project, weeek_create_project, weeek_update_project, weeek_archive_project, weeek_delete_project, weeek_create_board, weeek_update_board, weeek_delete_board, weeek_move_board, weeek_create_column, weeek_update_column, weeek_delete_column, weeek_move_column, weeek_list_portfolios, weeek_get_portfolio, weeek_create_portfolio, weeek_update_portfolio, weeek_delete_portfolio, weeek_list_tags, weeek_get_tag, weeek_create_tag, weeek_update_tag, weeek_delete_tag, weeek_get_workspace, weeek_get_profile
custom-fields	weeek_list_custom_fields, weeek_create_custom_field, weeek_update_custom_field, weeek_delete_custom_field, weeek_transfer_custom_field, weeek_move_custom_field, weeek_add_field_option, weeek_update_field_option, weeek_delete_field_option, weeek_move_field_option
crm	weeek_list_funnels, weeek_get_funnel, weeek_create_funnel, weeek_update_funnel, weeek_delete_funnel, weeek_list_statuses, weeek_get_status, weeek_create_status, weeek_update_status, weeek_delete_status, weeek_list_currencies, weeek_list_deals, weeek_get_deal, weeek_create_deal, weeek_update_deal, weeek_delete_deal, weeek_move_deal, weeek_add_deal_assignees, weeek_remove_deal_assignees, weeek_attach_organization, weeek_detach_organization, weeek_add_deal_task, weeek_move_deal_task, weeek_remove_deal_task, weeek_attach_deal_file, weeek_list_organizations, weeek_get_organization, weeek_create_organization, weeek_update_organization, weeek_delete_organization, weeek_list_contacts, weeek_get_contact, weeek_create_contact, weeek_update_contact, weeek_delete_contact, weeek_attach_contact, weeek_detach_contact, weeek_add_crm_tag, weeek_remove_crm_tag, weeek_add_detail, weeek_update_detail, weeek_delete_detail
all	所有工具集

weeek_version 始终可用。默认启用任务工具集：每次请求的工具架构为 16 871 字节；仅启用 crm 时为 32 290 字节；启用 all 时为 76 692 字节。未知名称会在启动时被拒绝，并列出有效名称。WEEEK 公共 API 的每个操作（157 个）都已注册，且除一个操作外，其他操作都对应一个工具（PATCH /crm/deals/{id}：API 会忽略其请求体的大部分内容，因此 weeek_update_deal 使用 PUT 和链接路由）——每次运行测试时，都会将注册表与随附的 OpenAPI 文档进行双向校验。

自定义字段的值无需额外工具集：weeek_get_task 会返回这些值，而 weeek_create_task / weeek_update_task 可按字段名称接收 fields: { "Estimate": 5, "Stage": "Review" }（创建时适用于全局字段和项目字段；任务创建后，可通过 weeek_update_task 设置看板自身的字段）。custom-fields 工具集用于管理字段本身——可在全局范围、项目、看板或 CRM 漏斗中管理。由于 API 只会从看板的任务中读取看板字段，不会从其他位置列出这些字段，因此空看板不会显示任何字段。 crm 工具集通过名称引用所有对象：漏斗、其中的状态、按标题（附带所属漏斗或状态）或 ID 查找的交易、组织、按全名查找的联系人、按代码查找的货币、按标题查找的标签。交易的自定义字段值与任务类似（按名称指定 fields；调用 weeek_create_deal 时也要传入 funnel）。地址、电子邮件和电话号码属于组织和联系人，可通过 weeek_add_detail / weeek_update_detail / weeek_delete_detail 修改。

从 1.0.0 升级：weeek_create_task / weeek_update_task 的 due 现在会实际设置截止日期（此前发送的键会被 API 忽略）；weeek_update_deal 现在会应用自定义字段和四个关联列表，并移除了 description（API 仅在创建时设置它）；weeek_create_organization / weeek_update_organization 接受一个 responsible，而不是 responsibles（列表会被忽略）；weeek_list_deals 移除了 sort: "amount"（API 会返回 500）；weeek_update_project 的 color 现在必须为 # 加六位十六进制数字；如果 API 返回 200，但标记为 success: false（例如达到计划限制），现在会将其报告为错误。

从 0.7.0 升级：没有重命名或移除任何工具；WEEEK_TOOLSETS=tasks 仍是默认值。可选择启用 crm 或 all。

从 0.5.0 升级：默认工具集在 0.6.0 中从 12 个工具增加到 24 个（另加 weeek_version），且 WEEEK_TOOLSETS=tasks 仍是默认值，因此除非选择启用 time、projects 或 all，否则没有其他变化。

WEEEK_TOOLSETS=tasks,crm npx -y weeek-mcp-smart   # add the CRM
WEEEK_TOOLSETS=all npx -y weeek-mcp-smart         # everything

开发

更新 API 规范快照

spec/weeek-openapi.json 是 WEEEK 公共 OpenAPI 文档的快照。测试 （tests/contract.test.ts）会检查服务器调用的每个操作是否都存在于其中，以及规范声明的每个操作是否都已注册——两个方向均为 157 项——因此 API 变更会导致测试失败，而不会在生产环境中带来意外。

需要 Node ≥ 18（用于 fetch），只有在设置了 REFRESH_SPEC_INTERFACE 时才需要 curl。

npm run refresh-spec            # re-extract from developers.weeek.net
npx vitest run tests/contract.test.ts

刷新成功后会打印一行，例如 wrote …/spec/weeek-openapi.json: openapi 3.1.1, 99 paths, 157 operations, 35 schemas (from weeek.yaml-<hash>.js)。

如果刷新因 DNS 或连接错误而失败，请阅读 scripts/refresh-spec.mjs 顶部的注释——其中列出了已知原因（VPN 解析器、隧道被阻止）以及对应的确切解决方法。

作者

Ilya Ivanchikov — GitHub · LinkedIn · Telegram · Channel