Skip to main content
Glama
MCP WorkBoard CrunchTools

MCP WorkBoard CrunchTools

by crunchtools

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-workboard built on Hummingbird Python base image

Related MCP server: Workato MCP Server

Naming Convention

Component

Name

GitHub repo

crunchtools/mcp-workboard

Container

quay.io/crunchtools/mcp-workboard

Python package (PyPI)

mcp-workboard-crunchtools

CLI command

mcp-workboard-crunchtools

Module import

mcp_workboard_crunchtools

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 user

  • workboard_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 owns

  • workboard_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 results

  • workboard_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 progress

  • workboard_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 user

  • workboard_get_workstream_activities_tool - Get workstream details with all action items

  • workboard_get_workstream_columns_tool - List the Kanban columns in use on a workstream

  • workboard_get_team_workstreams_tool - Get all workstreams belonging to a specific team

  • workboard_create_workstream_tool - Create a new workstream for a team

  • workboard_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

uvx mcp-workboard-crunchtools

With pip

pip install mcp-workboard-crunchtools

With Container

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

Configuration

Getting a WorkBoard API Token

  1. Log in to your WorkBoard instance

  2. Navigate to Admin Settings > API Configuration

  3. Generate a JWT API token

  4. 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-crunchtools

Or 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-workboard

OAuth 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:

  1. Register the public callback URL, e.g. https://workboard.example.com/callback, as the redirect URI of the WorkBoard app.

  2. Run the server with an HTTP transport and set WORKBOARD_OAUTH_REDIRECT_URI to that same URL. The proxy must route /callback to the server.

  3. 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.

  4. Call workboard_auth_status_tool to confirm (or workboard_auth_result_tool to 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.0

Variable

Default

Description

WORKBOARD_OAUTH_REDIRECT_URI

unset

Public URL of this server's /callback route. Required for workboard_auth_start_tool; the CLI login ignores it and uses http://localhost:8963/callback.

WORKBOARD_TOKEN_STORE_PATH

~/.config/mcp-workboard/tokens.json

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

  1. Token Protection

    • Stored as SecretStr (never accidentally logged)

    • Environment variable only (never in files or args)

    • Sanitized from all error messages

  2. Input Validation

    • Pydantic models for all inputs

    • Positive integer validation for IDs

    • Email validation for user creation

  3. API Hardening

    • Hardcoded API base URL (prevents SSRF)

    • TLS certificate validation

    • Request timeouts

    • Response size limits

  4. 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 sync

Run Tests

uv run pytest

Lint and Type Check

uv run ruff check src tests
uv run mypy src

Build Container

podman build -t mcp-workboard .

License

AGPL-3.0-or-later

Contributing

Contributions welcome! Please read SECURITY.md before submitting security-related changes.

Available Tools

27 tools
workboard_auth_result_toolWorkboard Auth Result ToolC
Read-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 ToolA
Read-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 ToolB
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolB
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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 ToolA
Read-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

    B3.4/5.0

    Scored across 27 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityActive
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that provides comprehensive access to LinkedIn data and functionality, enabling data retrieval and user account management through the HorizonDataWave API.
      26
      21 npm
      65
      JavaScript
      MIT
    • -
      license
      Not graded
      quality
      Not graded
      maintenance
      A 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
      -
    • F
      license
      B
      quality
      D
      maintenance
      A 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
      -