MCP WorkBoard CrunchTools
A secure MCP server for the WorkBoard OKR/strategy platform that lets an AI assistant authenticate and read or modify users, teams, objectives, key results, workstreams, and action items.
Authentication – Check credential/auth status, start browser-based OAuth authorization, and inspect the last auth redirect result.
Users – Get a user by ID or the current user, list users (team or org scope, with paging), create users (Data-Admin), and update user details.
Teams – List the teams you belong to and get all members of a team (IDs, emails).
Objectives – Get objectives owned by a user, get a team's objectives overlapping a date window (including past quarters), fetch one objective with its key results, get "my objectives" by auto-discovery or up to 25 IDs, and create team/individual objectives with key results (Data-Admin).
Key Results – List your own or another user's key results/metrics (optionally prior years), and update a key result's progress value with an optional check-in comment for weekly OKR updates.
Workstreams – List accessible team workstreams, get a workstream's full details and action items, read its Kanban columns, get a team's workstreams, create a workstream for a team, and update workstream properties (name, dates, pace, health, priority).
Action Items (Activities) – List activities with filters (owner, state, priority, effort), get a single activity, create a card on a workstream (state, owner, column, due date, etc.), and update an existing card.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@MCP WorkBoard CrunchTools show me my current goals"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
MCP WorkBoard CrunchTools
A secure MCP (Model Context Protocol) server for WorkBoard OKR and strategy execution platform.
Overview
This MCP server is designed to be:
Secure by default - Threat modeling, input validation, and token protection
No third-party services - Runs locally via stdio, your API token never leaves your machine
Cross-platform - Works on Linux, macOS, and Windows
Automatically updated - GitHub Actions monitor for CVEs and update dependencies
Containerized - Available at
quay.io/crunchtools/mcp-workboardbuilt on Hummingbird Python base image
Related MCP server: Workato MCP Server
Naming Convention
Component | Name |
GitHub repo | |
Container |
|
Python package (PyPI) |
|
CLI command |
|
Module import |
|
Why Hummingbird?
The container image is built on the Hummingbird Python base image from Project Hummingbird, which provides:
Minimal CVE exposure - Built with a minimal package set, dramatically reducing attack surface
Regular updates - Security patches applied promptly
Optimized for Python - Pre-configured with uv package manager
Production-ready - Proper signal handling and non-root user defaults
Features
User Management (4 tools)
workboard_get_user_tool- Get a user by ID or the current authenticated userworkboard_list_users_tool- List all users (Data-Admin role required)workboard_create_user_tool- Create a new user (Data-Admin role required)workboard_update_user_tool- Update an existing user
Objective Management (5 tools)
workboard_get_objectives_tool- Get all objectives a user ownsworkboard_get_team_objectives_tool- Get a team's objectives overlapping a date window, past quarters included (slow: reads every visible objective)workboard_get_objective_details_tool- Get details for a specific objective with key resultsworkboard_get_my_objectives_tool- Get the current user's owned objectives by ID (recommended)workboard_create_objective_tool- Create a new objective with key results (Data-Admin required)
Key Result Management (2 tools)
workboard_get_my_key_results_tool- List current user's key results with metric IDs and progressworkboard_update_key_result_tool- Update key result progress for weekly OKR check-ins
Workstream Management (6 tools)
workboard_get_workstreams_tool- Get team workstreams accessible to the authenticated userworkboard_get_workstream_activities_tool- Get workstream details with all action itemsworkboard_get_workstream_columns_tool- List the Kanban columns in use on a workstreamworkboard_get_team_workstreams_tool- Get all workstreams belonging to a specific teamworkboard_create_workstream_tool- Create a new workstream for a teamworkboard_update_workstream_tool- Update workstream properties (name, dates, pace, health, priority)
Authorization (3 tools)
workboard_auth_status_tool- Report auth mode, token store, and whether the credential works (GET /user)workboard_auth_start_tool- Return the WorkBoard authorize URL for browser approval (OAuth mode)workboard_auth_result_tool- Report the outcome of the most recent authorization redirect
Installation
With uvx (Recommended)
uvx mcp-workboard-crunchtoolsWith pip
pip install mcp-workboard-crunchtoolsWith Container
podman run -e WORKBOARD_API_TOKEN=your_token \
quay.io/crunchtools/mcp-workboardConfiguration
Getting a WorkBoard API Token
Log in to your WorkBoard instance
Navigate to Admin Settings > API Configuration
Generate a JWT API token
Copy the token immediately - store it securely
Add to Claude Code
claude mcp add mcp-workboard \
--env WORKBOARD_API_TOKEN=your_token_here \
-- uvx mcp-workboard-crunchtoolsOr for the container version:
claude mcp add mcp-workboard \
--env WORKBOARD_API_TOKEN=your_token_here \
-- podman run -i --rm -e WORKBOARD_API_TOKEN quay.io/crunchtools/mcp-workboardOAuth on a Server (Container Behind a Reverse Proxy)
In OAuth mode (WORKBOARD_CLIENT_ID + WORKBOARD_CLIENT_SECRET), a server
reachable over HTTPS can be re-authorized without a shell:
Register the public callback URL, e.g.
https://workboard.example.com/callback, as the redirect URI of the WorkBoard app.Run the server with an HTTP transport and set
WORKBOARD_OAUTH_REDIRECT_URIto that same URL. The proxy must route/callbackto the server.Call
workboard_auth_start_tool, open the URL it returns and approve. WorkBoard redirects to/callback; the server exchanges the code and saves the tokens to the token store. The authorization expires after 10 minutes.Call
workboard_auth_status_toolto confirm (orworkboard_auth_result_toolto see why it failed).
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.0Variable | Default | Description |
| unset | Public URL of this server's |
|
| Where OAuth tokens are stored |
Usage Examples
Get Current User
User: Who am I in WorkBoard?
Assistant: [calls workboard_get_user with no args]List All Users
User: List all WorkBoard users
Assistant: [calls workboard_list_users]Get User Objectives
User: Show me objectives for user 12345
Assistant: [calls workboard_get_objectives with user_id=12345]Get Objective Details
User: Get details on objective 67890 for user 12345
Assistant: [calls workboard_get_objective_details with user_id=12345, objective_id=67890]Get My Objectives
User: Show me my objectives (IDs: 2900058, 2900075, 2901770)
Assistant: [calls workboard_get_my_objectives with objective_ids=[2900058, 2900075, 2901770]]List My Key Results
User: Show me my key results
Assistant: [calls workboard_get_my_key_results]Update Key Result Progress
User: Update key result 12345 to 75
Assistant: [calls workboard_update_key_result with metric_id=12345, value="75"]Create an Objective
User: Create an objective called "Increase retention" owned by user@example.com
Assistant: [calls workboard_create_objective with name, owner, dates, and optional key_results]List Workstreams
User: Show me my workstreams
Assistant: [calls workboard_get_workstreams]Get Workstream Action Items
User: Show me the agenda for workstream 4130463
Assistant: [calls workboard_get_workstream_activities with ws_id=4130463]Security
This server was designed with security as a primary concern. See SECURITY.md for:
Threat model and attack vectors
Defense in depth architecture
Token handling best practices
Input validation rules
Key Security Features
Token Protection
Stored as SecretStr (never accidentally logged)
Environment variable only (never in files or args)
Sanitized from all error messages
Input Validation
Pydantic models for all inputs
Positive integer validation for IDs
Email validation for user creation
API Hardening
Hardcoded API base URL (prevents SSRF)
TLS certificate validation
Request timeouts
Response size limits
Automated CVE Scanning
GitHub Actions scan dependencies weekly
Automatic issues for security updates
Dependabot alerts enabled
Development
Setup
git clone https://github.com/crunchtools/mcp-workboard.git
cd mcp-workboard
uv syncRun Tests
uv run pytestLint and Type Check
uv run ruff check src tests
uv run mypy srcBuild Container
podman build -t mcp-workboard .License
AGPL-3.0-or-later
Contributing
Contributions welcome! Please read SECURITY.md before submitting security-related changes.
Links
Available Tools
27 toolsworkboard_auth_result_toolWorkboard Auth Result ToolCRead-only
Report the outcome of the most recent authorization redirect.
Inputs: no named parameters. Returns: result
workboard_auth_start_toolWorkboard Auth Start ToolA
Begin browser authorization and return the URL for the user to approve.
Open the returned URL. The user approves there, WorkBoard redirects back to this server, and the tokens are stored automatically -- nothing is copied back by hand. Then call workboard_auth_status_tool to confirm. Requires OAuth mode and WORKBOARD_OAUTH_REDIRECT_URI.
Inputs: no named parameters. Returns: result
workboard_auth_status_toolWorkboard Auth Status ToolARead-only
Report whether this server currently holds a usable WorkBoard credential.
Call this first. It says which auth mode is active, where tokens are stored, whether one exists, and verifies it with GET /user. If it is not usable, it says which tool fixes it.
Inputs: no named parameters. Returns: result
workboard_create_activity_toolWorkboard Create Activity ToolB
Create a new action item (card) on a WorkBoard workstream.
State must be "next", "doing", "done", or "pause". Priority must be "low", "med", or "high". Effort must be "easy", "medium", or "huge".
Inputs: ai_description (required), ai_note, ai_team, ai_owner, +6 more. Returns: object
workboard_create_objective_toolWorkboard Create Objective ToolA
Create a new objective with optional key results.
Creates Team or Individual objectives. The API has no update or delete for objectives — those are UI-only, so a name or date that is wrong at creation stays wrong until someone fixes it in the web UI.
This used to say Data-Admin was required and that instant JWT tokens cannot
create objectives. That is wrong: an instant token carrying
isSuperUser: false creates objectives and checks in progress against
their key results. Data-Admin does gate other calls, scope="org" on
workboard_list_users_tool among them, so do not generalise from that to
every write; test the specific call instead of assuming either way.
Team objectives must be tied to a team: pass team (a team ID from
workboard_get_teams_tool). Provide the objective name, owner, dates, and
optionally key results with targets. Each key result has a name and optional
start_value, target_value, and unit_type (e.g. "Number", "Currency", "Percent").
Inputs: name (required), owner (required), start_date (required), target_date (required), +5 more. Returns: object
workboard_create_user_toolWorkboard Create User ToolA
Create a new WorkBoard user (requires Data-Admin role).
Inputs: email (required), last_name (required), first_name (required), designation. Returns: object
workboard_create_workstream_toolWorkboard Create Workstream ToolA
Create a new workstream for a team.
Requires team manager or co-manager permissions.
Inputs: team_id (required), ws_name (required), ws_owner (required), ws_objective. Returns: object
workboard_get_activity_toolWorkboard Get Activity ToolBRead-only
Get a single WorkBoard action item by its ID.
Inputs: activity_id (required). Returns: object
workboard_get_my_key_results_toolWorkboard Get My Key Results ToolARead-only
List all key results (metrics) the current user owns or has access to.
Use this to find metric IDs and see current progress before updating with workboard_update_key_result_tool. Returns metric names, current values, targets, and IDs.
By default, only shows current year key results. Set include_prior_years=True to see key results from previous years.
Inputs: include_prior_years. Returns: object
workboard_get_my_objectives_toolWorkboard Get My Objectives ToolARead-only
Get the current authenticated user's objectives with key results.
This is the RECOMMENDED tool when users ask about "my objectives" or "my OKRs". It automatically determines the current user and discovers their objectives from their key results — no IDs needed.
Inputs: objective_ids. Returns: object
workboard_get_objective_details_toolWorkboard Get Objective Details ToolARead-only
Get full details for a single objective including all its key results.
Returns the objective name, progress, status, dates, and all key results (metrics) with their targets, progress, and update schedules.
Use workboard_get_user_tool (no arguments) to find the current user's ID.
Inputs: user_id (required), objective_id (required). Returns: object
workboard_get_objectives_toolWorkboard Get Objectives ToolARead-only
Get objectives owned by a WorkBoard user by their user ID.
Returns all objectives the user owns, with full pagination. Also exposes
workstreams and status_color fields on each objective when present.
Use workboard_get_user_tool (no arguments) to find the current user's ID. Use workboard_get_team_members_tool to resolve a name or email to a user ID.
Inputs: user_id (required). Returns: object
workboard_get_team_members_toolWorkboard Get Team Members ToolARead-only
Get all members of a WorkBoard team, including their user IDs and emails.
Use this to resolve a person's name or email to their WorkBoard user_id. Combine with workboard_get_objectives_tool(user_id) to fetch their OKRs.
Inputs: team_id (required). Returns: object
workboard_get_team_objectives_toolWorkboard Get Team Objectives ToolARead-only
Get a team's objectives whose dates overlap a window, past quarters included.
Use this for quarterly OKR reviews or snapshots, e.g. Q1 after March 31. Objectives on sub-teams are not included. Slow: it reads every objective you can see, which takes about a minute.
Use workboard_get_teams_tool to find team IDs.
Inputs: team_id (required), end_date (required), start_date (required). Returns: object
workboard_get_teams_toolWorkboard Get Teams ToolARead-only
Get all teams the authenticated user belongs to.
Returns team IDs, names, and owner user IDs. Use workboard_get_team_members_tool to get the full member list (with user_ids) for a specific team.
Inputs: no named parameters. Returns: object
workboard_get_team_workstreams_toolWorkboard Get Team Workstreams ToolARead-only
Get all workstreams belonging to a specific team.
Use workboard_get_teams_tool to find team IDs first.
Inputs: team_id (required). Returns: object
workboard_get_user_key_results_toolWorkboard Get User Key Results ToolARead-only
List key results (metrics) for a specific WorkBoard user by their user ID.
Use this to see KRs owned by or associated with any user — for example, to review a direct report's key results before a 1:1. Skills layer maps organizational roles (e.g. "direct report") to user IDs; this tool only knows about WorkBoard user IDs.
Use workboard_get_teams_tool and workboard_get_team_members_tool to resolve a person's name to their user ID.
By default, only shows current year key results. Set include_prior_years=True to see key results from previous years.
Inputs: user_id (required), include_prior_years. Returns: object
workboard_get_user_toolWorkboard Get User ToolARead-only
Get a WorkBoard user by ID, or the current authenticated user.
Inputs: user_id. Returns: object
workboard_get_workstream_activities_toolWorkboard Get Workstream Activities ToolBRead-only
Get a workstream's full details including all action items.
Returns the workstream metadata plus every action item with descriptions, owners, due dates, comments, sub-actions, and attached files.
Inputs: ws_id (required). Returns: object
workboard_get_workstream_columns_toolWorkboard Get Workstream Columns ToolARead-only
Get the custom Kanban columns in use on a workstream.
The API has no column endpoint, so columns are read off the workstream's action items. A column with no cards in it will not appear. Use the column_id values to tell which column a card sits in.
Inputs: ws_id (required). Returns: object
workboard_get_workstreams_toolWorkboard Get Workstreams ToolARead-only
Get team workstreams accessible to the authenticated user.
Returns all team workstreams the user has access to. Personal workstreams are not included. Optionally filter to a single workstream by ID.
Inputs: ws_id. Returns: object
workboard_list_activities_toolWorkboard List Activities ToolARead-only
List action items accessible to the authenticated user.
Returns up to 15 action items by default. Use limit and offset for pagination. Filter by owner, state, priority, or effort to narrow results.
Inputs: limit, offset, ai_owner, ai_state, +2 more. Returns: object
workboard_list_users_toolWorkboard List Users ToolARead-only
List WorkBoard users.
scope="team" (default) returns members of teams you can see and works for any account. scope="org" returns every user in the organization and requires a Data-Admin token. Returns up to 100 users; use limit and offset to page.
Inputs: limit, scope, offset. Returns: object
workboard_update_activity_toolWorkboard Update Activity ToolA
Update an existing WorkBoard action item.
Performs read-before-write to confirm the action item exists. Only provided fields are updated. State must be "next", "doing", "done", or "pause". Priority must be "low", "med", or "high". Effort must be "easy", "medium", or "huge".
Inputs: activity_id (required), ai_note, ai_owner, ai_state, +5 more. Returns: object
workboard_update_key_result_toolWorkboard Update Key Result ToolA
Update progress on a key result (metric). This is the primary tool for weekly OKR check-ins — update a key result's value without logging into WorkBoard.
Use workboard_get_my_key_results_tool to find metric IDs first.
Inputs: value (required), metric_id (required), comment. Returns: object
workboard_update_user_toolWorkboard Update User ToolC
Update an existing WorkBoard user.
Inputs: user_id (required), email, last_name, first_name, +1 more. Returns: object
workboard_update_workstream_toolWorkboard Update Workstream ToolA
Update an existing workstream's properties.
Performs read-before-write to confirm the workstream exists. Requires team manager or co-manager permissions. Pace must be "slow", "fast", or "steady". Health must be "ok", "good", or "risk". Priority must be "p1" through "p5".
Inputs: ws_id (required), ws_name, ws_pace, ws_health, +3 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Several tools overlap significantly: workboard_get_workstreams_tool vs workboard_get_team_workstreams_tool, workboard_list_activities_tool vs workboard_get_workstream_activities_tool, and four different objective getters (get_objectives, get_my_objectives, get_team_objectives, get_objective_details) create potential misselection. Descriptions do help clarify boundaries, but the distinctions are not always obvious at a glance.
All tool names follow a consistent workboard_verb_noun_tool snake_case pattern. Minor deviations exist in verb choice (get vs list for similar operations) and in qualifier specificity (get_workstreams vs get_team_workstreams), but the overall convention is predictable.
27 tools is on the heavy side for an OKR/workstream integration. While many tools correspond to distinct operations, there is clear redundancy among getter tools and auth helpers, suggesting the surface could be trimmed without losing functionality.
Core read, create, and update workflows for users, teams, workstreams, activities, objectives, and key results are covered. However, there are notable gaps: no delete operations anywhere, no separate update for objectives (noted as an API limitation), and no tools for comments or file attachments mentioned in activity descriptions.
Maintenance
Related MCP Connectors
Model Context Protocol server for Studex tools, notifications, and profile integrations
Model Context Protocol server for the Apideck Unified API. Connect any MCP-compatible agent framework to 100+ accounting systems, HRIS platforms, file storage providers, and more through one integration. More information https://www.apideck.com/mcp-server
A Model Context Protocol server for Wix AI tools
Siftable MCP server for governed work, knowledge, calendar, people, datasets, and Vault.
Related MCP Servers
- AlicenseBqualityDmaintenanceA Model Context Protocol server that provides comprehensive access to LinkedIn data and functionality, enabling data retrieval and user account management through the HorizonDataWave API.2621 npm65JavaScriptMIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that provides seamless interaction with Workato's API through custom AI tools, enabling management of recipes, connections, connectors, folders, and activity logs.4MIT
- -licenseNot gradedqualityNot gradedmaintenanceA production-grade Model Context Protocol server that enables secure management of context data through a React dashboard, supporting ZIP processing, context approval workflows, and system monitoring.547 npm-
- FlicenseBqualityDmaintenanceA Model Context Protocol server providing access to WeWork project management data, enabling project search, task analysis, and statistics retrieval through Claude and other LLM clients.6-