Workel MCP Server

这是 Workel 的官方 Model Context Protocol 服务器——一个基于 Workel Public API v1 的轻量无状态客户端。它将 Workel 工作区以一组范围明确的小工具形式暴露给 AI 代理（Claude、OpenAI Agents SDK 或任何其他支持 MCP 的客户端）。真正重要的所有规则——这个密钥能看什么、能写什么、写多快——都存在于 Workel API 本身；本包不拥有密钥本身没有的任何权限。使用同一密钥发出的 curl 请求能做到的事，这个服务器也能做到，不多不少。

关于各客户端的完整配置（Claude Desktop、Claude Code、项目级 .mcp.json 以及 OpenAI Agents SDK），请参阅 Workel 开发者文档。

使用 Claude？你可能不需要这个包

Workel 运行一个托管式 MCP 服务器。在 Claude 中通过 Settings → Connectors → Add custom connector 添加即可：

https://mcp.workel.com/mcp

你登录 Workel，选择一个工作区，就连接成功了。无需安装、无需配置文件、也无需 API 密钥——你永远不会看到密钥，Claude 也不会。授权需要你拥有所选工作区的 owner 或 admin 角色，并且每次请求都会重新检查连接，因此一旦失去该角色，连接就会自动断开，无需任何人记得去撤销密钥。

它可以读取你的项目、任务、评论、事件和成员——包括任务的封面图片、附件和完整历史——并且可以创建任务、评论和事件，以及更新现有任务：重命名、修改日期和优先级、在列和项目之间移动、更改负责人。它不能删除任何内容，也不能上传文件。读取和写入权限在同意屏幕上分别列出，因此你是在知情的情况下批准，而不是事后才发现。

连接多个工作区

一个连接对应一个工作区，因为其背后的凭据绑定到该工作区。要访问第二个工作区，再次添加连接器并选择另一个工作区——每个连接都会单独注册，因此它们可以共存，并且每个连接都以工作区名称显示（workel — Acme），而不是显示为无法区分的相同条目。

有一点需要注意：重新授权现有连接会移动它，而不是添加它。 对已添加的连接器再次进行同意流程会替换其凭据并禁用旧凭据，因此该连接会切换到你所选的工作区。如果你两个都想要，请添加新连接器，而不是重新授权已有的那个。

Related MCP server: Google Workspace MCP Server

自行运行

本包适用于托管服务器未覆盖的场景：Claude Code、CI 代理、OpenAI Agents SDK——任何你想自行运行进程并持有凭据的地方。以下所有内容都与此相关。

它处理多个工作区的方式不同，并且对这种用例更优：将 WORKEL_API_KEYS 设置为逗号分隔的列表，每个工作区一个密钥，所有工具都会获得一个 workspace 参数来指定在哪个工作区中操作。无论你配置多少个工作区，十个工具始终是十个工具，而不会按工作区成倍增加——这一点很重要，因为每个工具定义都是模型每轮都要付费的上下文。

开始之前，先铸造一个专用的只读密钥

在将任何 AI 客户端指向此服务器之前，请前往 Workel → Settings → Developers 并为此目的专门铸造一个新的 API 密钥——不要复用其他集成已持有的密钥。铸造密钥需要 owner 或 admin 角色。只授予本版本工具实际使用的 read:* 作用域（read:projects、read:tasks、read:members、read:events——见下方 工具）；除非你已深思熟虑决定让代理自行在工作区中创建和编辑内容，否则保持所有 write:* 作用域不勾选。每台机器或代理使用一个密钥，命名时记得它以后是做什么用的，如果某台机器退役或某个客户端被入侵，请在 Settings → Developers 中撤销那一个密钥，而不是轮换多个工具共用的密钥——撤销是即时的，下一次请求即生效。

在接触下文所述标志之前，有两件事值得理解：

• WORKEL_ENABLE_WRITES 是本地操作者同意标志，不是授权边界。 它只能收窄已限定作用域的密钥所提供的能力，绝不能扩大——而且由于它存在于配置文件或环境变量中，而 AI 编码代理通常对这些文件有写权限，因此运行在你机器上的代理可以自行将其改回 true。本地标志不是不可信代理能自觉不去碰的东西。密钥自身的作用域——在铸造时有意授予、随时可撤销——才是真正的闸门。

• WORKEL_API_BASE_URL 覆盖会将你的密钥发送到另一台主机。 此服务器发出的每个请求都在 Authorization 头中携带你的密钥。如果 WORKEL_API_BASE_URL 指向你不控制的 URL，该主机将在每次调用时收到你的密钥。正是出于这个原因，此客户端拒绝普通的 http:// 覆盖，除非目标是 localhost/127.0.0.1/[::1]。同样的逻辑也适用于粘贴到任何文件中的真实密钥：如果它曾被提交到 git，轮换密钥是唯一真正的修复方法——git 历史是永恒的。之后删除该行的提交并不会将其从仓库历史中移除，期间克隆过仓库的任何人仍然持有旧密钥。

安装

npx -y @workel/mcp@0.4.0

固定版本——上面的 0.4.0 是本包的当前版本；在固定之前先运行 npm view @workel/mcp version 查看最新版本。下面未固定版本的形式仅为方便，适合一次性手动试用，不适合任何由代理配置无人值守运行的情况：

npx -y @workel/mcp

环境变量

doctor

每当你的 MCP 客户端仅报告"服务器启动失败"而没有更多细节时，运行 npx -y @workel/mcp@0.4.0 doctor。它会执行与服务器自身完全相同的启动检查——加载配置，然后探测 GET /me——并将纯文本报告打印到 stdout，而不是尝试使用 MCP 协议通信：

base URL: https://api.workel.com/api/public/v1
workspace: Acme Inc
key: ci-key
scopes: read:projects, read:tasks
2 tools would register: workel_whoami, workel_list_projects
write budget: 59/60 remaining this minute

doctor 从不启动传输层，也从不与你的 MCP 客户端通信——它是一个你在终端中运行的独立命令，成功时以退出码 0 退出，任何失败（WORKEL_API_KEY 缺失或无效、API 不可达、或 API 拒绝的密钥）时以 1 退出。与服务器正常启动时打印到 stderr 的单行摘要（默认 URL 时省略 base URL）不同，doctor 始终打印实际生效的 base URL——包括默认值——因为运行 doctor 正是被篡改的 WORKEL_API_BASE_URL 需要被暴露的时刻。

工具

本版本注册了以下只读工具。workel_whoami 完全不需要作用域，可与任何有效密钥配合使用；其他每个工具仅在密钥的作用域（通过上述 GET /me 探测发现）包含所列作用域时才被注册。列表工具默认每次调用返回 25 条结果（最多 50 条——此客户端有意将上限设得低于 API 自身的 100 条，参见 src/tools/conventions.ts），并通过不透明的 cursor / next_cursor 对进行分页。

写入工具

四个，而且只有当两个条件同时满足时才会注册：密钥携带匹配的 write:* 作用域并且设置了 WORKEL_ENABLE_WRITES=true。单独满足任何一个都不会注册任何工具，因此只读安装永远看不到它们。

没有任何工具会删除内容。workel_update_task 被标注为 destructiveHint: true，因此遵守注解的客户端会在每次调用前提示；读取工具被标注为只读，无需提示即可运行。

托管服务器 mcp.workel.com 启用了写入功能，因此那里可以使用全部十三个工具。

限制

replayed 并不证明唯一性。 此服务器工具执行的每次写入都会携带 Idempotency-Key，而 Workel API 的幂等存储（保留 24 小时，按调用密钥隔离）会对使用相同密钥和相同请求体的重复尝试重放完全相同的响应——第二次尝试会报告 replayed: true，并且不会再次创建或更改任何内容。

replayed: false 表示这次特定尝试确实执行了——但这并不意味着其他地方不存在重复项。具体来说：错误响应永远不会被缓存，因此失败后重试总是会真实地重新执行；幂等记录在 24 小时后过期，因此很晚的重试会真实地重新执行；而且存储按 API 密钥隔离，因此在不同密钥下发送的相同字面量 Idempotency-Key 值永远不会与第一个密钥产生冲突——也永远不会防止由第一个密钥创建的重复项。除非工具调用在两次尝试中显式复用相同的幂等密钥，否则每次尝试在服务器看来都是一次真正独立的写入。