io.github.crunchtools/workboard

Official

by crunchtools · Python

MCP Workboard

Secure MCP server for WorkBoard OKR and strategy execution platform

Manages OKR and strategy execution on the WorkBoard platform.

README.md7 KBView on GitHub

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 - Comprehensive 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

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 - Get a user by ID or the current authenticated user
workboard_list_users - List all users (Data-Admin role required)
workboard_create_user - Create a new user (Data-Admin role required)
workboard_update_user - Update an existing user

Objective Management (4 tools)

workboard_get_objectives - Get objectives associated with a user (API capped at 15)
workboard_get_objective_details - Get details for a specific objective with key results
workboard_get_my_objectives - Get the current user's owned objectives by ID (recommended)
workboard_create_objective - Create a new objective with key results (Data-Admin required)

Key Result Management (2 tools)

workboard_get_my_key_results - List current user's key results with metric IDs and progress
workboard_update_key_result - Update key result progress for weekly OKR check-ins

Workstream Management (5 tools)

workboard_get_workstreams - Get team workstreams accessible to the authenticated user
workboard_get_workstream_activities - Get workstream details with all action items
workboard_get_team_workstreams - Get all workstreams belonging to a specific team
workboard_create_workstream - Create a new workstream for a team
workboard_update_workstream - Update workstream properties (name, dates, pace, health, priority)

Installation

With uvx (Recommended)

bash

uvx mcp-workboard-crunchtools

With pip

bash

pip install mcp-workboard-crunchtools

With Container

bash

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

Configuration

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

bash

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

Or for the container version:

bash

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

Usage Examples

Get Current User

code

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

List All Users

code

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

Get User Objectives

code

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

Get Objective Details

code

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

code

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

code

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

Update Key Result Progress

code

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

Create an Objective

code

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

code

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

Get Workstream Action Items

code

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

bash

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

Run Tests

bash

uv run pytest

Lint and Type Check

bash

uv run ruff check src tests
uv run mypy src

Build Container

bash

podman build -t mcp-workboard .

License

AGPL-3.0-or-later

Contributing

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

Links

Install

claude_desktop_config.json

{
  "mcpServers": {
    "workboard": {
      "command": "uvx",
      "args": [
        "mcp-workboard-crunchtools"
      ]
    }
  }
}