MCP Workboard

MCP WorkBoard CrunchTools

为 WorkBoard OKR 和战略执行平台提供的安全 MCP（Model Context Protocol）服务。

概述

此 MCP 服务旨在实现：

• 默认安全 - 威胁建模、输入验证和令牌保护
• 不使用第三方服务 - 通过 stdio 在本地运行，API 令牌不会离开你的计算机
• 跨平台 - 支持 Linux、macOS 和 Windows
• 自动更新 - GitHub Actions 监控 CVE 并更新依赖项
• 容器化 - 可通过 quay.io/crunchtools/mcp-workboard 获取，基于 Hummingbird Python 基础镜像构建

命名约定

组件	名称
GitHub 仓库	crunchtools/mcp-workboard
容器	quay.io/crunchtools/mcp-workboard
Python 包（PyPI）	mcp-workboard-crunchtools
CLI 命令	mcp-workboard-crunchtools
模块导入	mcp_workboard_crunchtools

为什么选择 Hummingbird？

容器镜像基于 Project Hummingbird 提供的 Hummingbird Python 基础镜像 构建，该镜像提供：

• 最大限度减少 CVE 暴露 - 使用最精简的软件包集构建，大幅缩小攻击面
• 定期更新 - 及时应用安全补丁
• 针对 Python 优化 - 预配置 uv 包管理器
• 可用于生产环境 - 正确处理信号，并默认使用非 root 用户

功能

用户管理（4 个工具）

• workboard_get_user_tool - 按 ID 获取用户，或获取当前已认证用户
• workboard_list_users_tool - 列出所有用户（需要 Data-Admin 角色）
• workboard_create_user_tool - 创建新用户（需要 Data-Admin 角色）
• workboard_update_user_tool - 更新现有用户

目标管理（5 个工具）

• workboard_get_objectives_tool - 获取用户拥有的所有目标
• workboard_get_team_objectives_tool - 获取与指定日期范围重叠的团队目标，包括过往季度的目标（速度较慢：会读取所有可见目标）
• workboard_get_objective_details_tool - 获取指定目标的详细信息和关键结果
• workboard_get_my_objectives_tool - 按 ID 获取当前用户拥有的目标（推荐）
• workboard_create_objective_tool - 创建包含关键结果的新目标（需要 Data-Admin 权限）

关键结果管理（2 个工具）

• workboard_get_my_key_results_tool - 列出当前用户的关键结果，包括指标 ID 和进度
• workboard_update_key_result_tool - 更新关键结果进度，用于每周 OKR 检查

工作流管理（6 个工具）

• workboard_get_workstreams_tool - 获取已认证用户可访问的团队工作流
• workboard_get_workstream_activities_tool - 获取工作流详细信息及所有行动项
• workboard_get_workstream_columns_tool - 列出工作流正在使用的看板列
• workboard_get_team_workstreams_tool - 获取特定团队的所有工作流
• workboard_create_workstream_tool - 为团队创建新工作流
• workboard_update_workstream_tool - 更新工作流属性（名称、日期、进度、健康状况、优先级）

授权（3 个工具）

• workboard_auth_status_tool - 报告授权模式、令牌存储位置，以及凭据是否有效（GET /user）
• workboard_auth_start_tool - 返回 WorkBoard 授权 URL，以便在浏览器中批准（OAuth 模式）
• workboard_auth_result_tool - 报告最近一次授权重定向的结果

安装

使用 uvx（推荐）

uvx mcp-workboard-crunchtools

使用 pip

pip install mcp-workboard-crunchtools

使用容器

podman run -e WORKBOARD_API_TOKEN=your_token \
    quay.io/crunchtools/mcp-workboard

配置

获取 WorkBoard API 令牌

1. 登录 WorkBoard 实例
2. 前往 Admin Settings > API Configuration
3. 生成 JWT API 令牌
4. 立即复制令牌并妥善保存

添加到 Claude Code

claude mcp add mcp-workboard \
    --env WORKBOARD_API_TOKEN=your_token_here \
    -- uvx mcp-workboard-crunchtools

或使用容器版本：

claude mcp add mcp-workboard \
    --env WORKBOARD_API_TOKEN=your_token_here \
    -- podman run -i --rm -e WORKBOARD_API_TOKEN quay.io/crunchtools/mcp-workboard

服务器上的 OAuth（反向代理后的容器）

在 OAuth 模式下（WORKBOARD_CLIENT_ID + WORKBOARD_CLIENT_SECRET），可通过 HTTPS 访问的服务器无需使用 shell 即可重新授权：

1. 将公共回调 URL（例如 https://workboard.example.com/callback）注册为 WorkBoard 应用的重定向 URI。
2. 使用 HTTP 传输运行服务器，并将 WORKBOARD_OAUTH_REDIRECT_URI 设置为同一个 URL。代理必须将 /callback 路由到服务器。
3. 调用 workboard_auth_start_tool，打开其返回的 URL 并批准授权。WorkBoard 会重定向到 /callback；服务器会交换授权码，并将令牌保存到令牌存储中。授权将在 10 分钟后过期。
4. 调用 workboard_auth_status_tool 确认状态（或调用 workboard_auth_result_tool 查看失败原因）。

podman run -p 8000:8000 \
    -e WORKBOARD_CLIENT_ID -e WORKBOARD_CLIENT_SECRET \
    -e WORKBOARD_OAUTH_REDIRECT_URI=https://workboard.example.com/callback \
    -e WORKBOARD_TOKEN_STORE_PATH=/data/tokens.json -v workboard-tokens:/data:Z \
    quay.io/crunchtools/mcp-workboard --transport streamable-http --host 0.0.0.0

变量	默认值	描述
WORKBOARD_OAUTH_REDIRECT_URI	未设置	此服务器 /callback 路由的公共 URL。workboard_auth_start_tool 必须设置此变量；CLI login 会忽略此变量，并使用 http://localhost:8963/callback。
WORKBOARD_TOKEN_STORE_PATH	~/.config/mcp-workboard/tokens.json	OAuth 令牌的存储位置

使用示例

获取当前用户

User: Who am I in WorkBoard?
Assistant: [calls workboard_get_user with no args]

列出所有用户

User: List all WorkBoard users
Assistant: [calls workboard_list_users]

获取用户目标

User: Show me objectives for user 12345
Assistant: [calls workboard_get_objectives with user_id=12345]

获取目标详情

User: Get details on objective 67890 for user 12345
Assistant: [calls workboard_get_objective_details with user_id=12345, objective_id=67890]

获取我的目标

User: Show me my objectives (IDs: 2900058, 2900075, 2901770)
Assistant: [calls workboard_get_my_objectives with objective_ids=[2900058, 2900075, 2901770]]

列出我的关键结果

User: Show me my key results
Assistant: [calls workboard_get_my_key_results]

更新关键结果进度

User: Update key result 12345 to 75
Assistant: [calls workboard_update_key_result with metric_id=12345, value="75"]

创建目标

User: Create an objective called "Increase retention" owned by [email protected]
Assistant: [calls workboard_create_objective with name, owner, dates, and optional key_results]

列出工作流

User: Show me my workstreams
Assistant: [calls workboard_get_workstreams]

获取工作流行动项

User: Show me the agenda for workstream 4130463
Assistant: [calls workboard_get_workstream_activities with ws_id=4130463]

安全

此服务将安全作为首要考量进行设计。请参阅 SECURITY.md，了解：

• 威胁模型和攻击途径
• 深度防御架构
• 令牌处理最佳实践
• 输入验证规则

主要安全功能

1. 令牌保护

   • 以 SecretStr 格式存储（绝不会意外写入日志）
   • 仅使用环境变量（不会存储在文件或参数中）
   • 从所有错误消息中清除敏感信息

2. 输入验证

   • 所有输入均使用 Pydantic 模型
   • 对 ID 进行正整数验证
   • 创建用户时验证电子邮件

3. API 加固

   • 硬编码 API 基础 URL（防止 SSRF）
   • TLS 证书验证
   • 请求超时
   • 响应大小限制

4. 自动 CVE 扫描

   • GitHub Actions 每周扫描依赖项
   • 针对安全更新自动创建问题
   • 已启用 Dependabot 警报

开发

设置

git clone https://github.com/crunchtools/mcp-workboard.git
cd mcp-workboard
uv sync

运行测试

uv run pytest

代码检查和类型检查

uv run ruff check src tests
uv run mypy src

构建容器

podman build -t mcp-workboard .

许可证

AGPL-3.0-or-later

贡献

欢迎贡献！提交与安全相关的更改前，请先阅读 SECURITY.md。

链接

• WorkBoard API 文档
• FastMCP 文档
• MCP 规范
• crunchtools.com