MCP Workboard

Secure MCP server for WorkBoard OKR and strategy execution platform
Open source Open in the app JSON README (API)
About

Secure MCP server for WorkBoard OKR and strategy execution platform
Details

Kind: MCP servers
Topic: No topic detected
Publisher: crunchtools
Origin: official
Category: ferramentas
Transport: local
Version: 0.6.1
Stars: 1
Forks: 2
Open pull requests: 2
Last push: 2026-09-06T05:03:42Z
Repository state: ativo
Language: Python
License: AGPL-3.0
Added: 2026-08-29 03:02:38
Updated: 2026-08-29 03:02:38
Origin id: io.github.crunchtools/workboard
README

# 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](https://quay.io/repository/hummingbird/python) base image

## Naming Convention

| Component | Name |
|-----------|------|
| GitHub repo | [crunchtools/mcp-workboard](https://github.com/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](https://quay.io/repository/hummingbird/python) from [Project Hummingbird](https://github.com/hummingbird-project), 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

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

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

```
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](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

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

- [WorkBoard API Documentation](https://www.myworkboard.com/wb/apis/)
- [FastMCP Documentation](https://gofastmcp.com/)
- [MCP Specification](https://modelcontextprotocol.io/)
- [crunchtools.com](https://crunchtools.com)

<!-- mcp-name: io.github.crunchtools/workboard -->
MCP Workboard

About

Details

README

More
