@betterqa/bugboard-mcp

MCP (Model Context Protocol) server for BugBoard. Allows AI agents like Claude Code to create and manage bugs directly from the terminal.

What can you do with this?

Once configured, you can talk to Claude naturally and it will manage your bugs:

File bugs without leaving your IDE

"I just found a bug - the checkout fails when the cart has more than 10 items.
Log it as high severity."

Claude creates the bug with all details, returns the bug ID, and you keep coding.

Check project status during standup

"What critical bugs do we have open right now?"

Get an instant summary without opening a browser.

Pick up a bug to fix

"Claim bug BUG-000234 and assign it to me"

Bug set to In Progress, assigned to you - ready to code.

Mark bug as Ready For QA

"I just fixed BUG-000234. Mark it as RFQA with comment 'Fixed in PR #567'"

Bug moved to In QA, comment added - QA team notified.

Triage incoming bugs

"Show me all bugs in triage. Then mark BUG-000567 as confirmed
and assign it to [email protected]"

Review and process bugs without context-switching.

Document your investigation

"Add a comment to BUG-000890: Reproduced on Chrome 120.
The issue is in the payment validation logic, investigating further."

Keep your team updated as you debug.

AI-assisted bug reports

When Claude helps you debug, it can file detailed bug reports automatically:

"This function is throwing a null pointer - can you figure out why
and file a bug if it's a real issue?"

Claude investigates, identifies the root cause, and files a complete bug report.

Installation

npm install -g @betterqa/bugboard-mcp

Or use directly with npx:

npx @betterqa/bugboard-mcp

Setup

1. Get your API key

1. Go to BugBoard: https://bugboard.co/app
2. Navigate to your project's Settings > API Keys
3. Create a new API key with bug management permissions
4. Copy the key

2. Configure your AI tool

This MCP server works with any tool that supports the Model Context Protocol. Choose your tool below:

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "bugboard": {
      "command": "npx",
      "args": ["@betterqa/bugboard-mcp"],
      "env": {
        "BUGBOARD_API_KEY": "your-api-key-here",
        "BUGBOARD_URL": "https://szbjzmpklprwjvgpmgga.supabase.co/functions/v1"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json globally):

{
  "mcpServers": {
    "bugboard": {
      "command": "npx",
      "args": ["@betterqa/bugboard-mcp"],
      "env": {
        "BUGBOARD_API_KEY": "your-api-key-here",
        "BUGBOARD_URL": "https://szbjzmpklprwjvgpmgga.supabase.co/functions/v1"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "bugboard": {
      "command": "npx",
      "args": ["@betterqa/bugboard-mcp"],
      "env": {
        "BUGBOARD_API_KEY": "your-api-key-here",
        "BUGBOARD_URL": "https://szbjzmpklprwjvgpmgga.supabase.co/functions/v1"
      }
    }
  }
}

VS Code + Continue

Add to your Continue config (~/.continue/config.json):

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "npx",
          "args": ["@betterqa/bugboard-mcp"]
        },
        "env": {
          "BUGBOARD_API_KEY": "your-api-key-here",
          "BUGBOARD_URL": "https://szbjzmpklprwjvgpmgga.supabase.co/functions/v1"
        }
      }
    ]
  }
}

3. Restart your tool

After updating settings, restart your AI tool for the MCP server to be loaded.

Available tools

create_bug

Create a new bug in BugBoard.

Parameters:

• title (required): Short, descriptive title
• description: Detailed description
• severity: critical | high | medium | low
• priority: critical | high | medium | low
• steps_to_reproduce: Step-by-step reproduction instructions
• expected_result: What should happen
• actual_result: What actually happened
• module: Component/module name
• labels: Array of tags (e.g., ["ui", "regression"])
• environment: Browser, OS, version details

Example:

Create a bug: The login button is not responding on mobile Safari.
Severity: high
Steps: Open the app on iOS Safari, tap the login button
Expected: Login form should appear
Actual: Nothing happens

list_bugs

List bugs with optional filters.

Parameters:

• status: triage | backlog | todo | in_progress | in_review | in_qa | ready_to_release | closed
• severity: critical | high | medium | low
• limit: Maximum bugs to return (default: 20)

Example:

List all critical bugs that are in triage

get_bug

Get detailed information about a specific bug.

Parameters:

• bug_id (required): Bug ID (e.g., "BUG-000123")

Example:

Get details for bug BUG-000456

update_bug

Update an existing bug.

Parameters:

• bug_id (required): Bug ID to update
• status: New status
• severity: New severity
• priority: New priority
• title: Updated title
• description: Updated description
• assigned_to: User email or UUID

Example:

Mark bug BUG-000456 as fixed

add_comment

Add a comment to a bug.

Parameters:

• bug_id (required): Bug ID
• content (required): Comment text

Example:

Add comment to BUG-000456: "Reproduced on Chrome 120, investigating"

claim_bug

Pick up a bug to work on. Sets status to In Progress.

Parameters:

• bug_id (required): Bug ID to claim
• assigned_to: Your email to assign the bug to yourself

Example:

Claim bug BUG-000456 and assign to [email protected]

mark_rfqa

Mark a bug as Ready For QA (RFQA). Use when you've finished fixing.

Parameters:

• bug_id (required): Bug ID to mark as RFQA
• comment: Optional comment about the fix

Example:

Mark BUG-000456 as RFQA with comment "Fixed in PR #123"

AI-Powered Tools (Requires SUPABASE_ANON_KEY)

The following tools leverage AI for advanced analysis and generation:

analyze_bugs

Find patterns in bugs - identify hotspots, trends, common labels, and repeated failures.

Parameters:

• days_back: Number of days to analyze (default: 30)
• include_closed: Include closed bugs (default: false)

Example:

What patterns do you see in our recent bugs?
Which module has the most critical bugs?

check_release_readiness

Check if a release is ready to ship by analyzing pass rates, open bugs, blockers, and coverage.

Parameters:

• release_id: Specific release ID to check
• suite_id: Check by test suite ID
• execution_id: Check by specific test execution ID
• threshold_pass_rate: Minimum pass rate required (default: 95)

Example:

Is the v2.3 release ready to ship?
What's blocking the checkout release?

generate_test_cases

Generate test cases from requirements or feature descriptions using AI.

Parameters:

• requirement (required): Feature description or PRD text
• suite_id: Target test suite to add generated tests
• check_duplicates: Check existing coverage (default: true)
• test_type: functional | regression | smoke | integration | e2e
• count: Number of test cases to generate (default: 5)

Example:

Generate test cases for the password reset flow
Create 10 integration tests for the checkout API

generate_test_plan

Generate a structured test plan from a PRD or specification document.

Parameters:

• prd_text (required): PRD or requirements document text
• format: markdown | json (default: markdown)
• include_estimates: Include effort estimates (default: false)

Example:

Create a test plan for this PRD: [paste PRD text]

create_bug_from_screenshot

Create a bug from a screenshot. AI analyzes the image to extract bug details.

Parameters:

• image_path: Path to screenshot file (PNG, JPG, etc.)
• image_base64: Base64-encoded image data (alternative to path)
• context: Additional context about what was being tested
• auto_create: Create bug immediately or return for review (default: false)

Example:

Here's a screenshot of the bug I found [attach image]
Analyze this screenshot and create a bug - I was testing the checkout flow

Environment variables

| Variable | Required | Description | | ------------------- | -------- | ------------------------------------------------------ | | BUGBOARD_API_KEY | Yes | Your BugBoard API key | | BUGBOARD_URL | No | API base URL (defaults to production) | | SUPABASE_URL | No | Supabase URL (for AI features, defaults to production) | | SUPABASE_ANON_KEY | No | Supabase anon key (required for AI-powered tools) | | TESTKUBE_URL | No | Testkube API URL (for Testkube integration) | | TESTKUBE_TOKEN | No | Testkube API token | | TESTKUBE_ORG | No | Testkube Control Plane organization | | TESTKUBE_ENV | No | Testkube Control Plane environment |

Testkube Integration (Requires TESTKUBE_URL)

Run and monitor Kubernetes-native tests directly from your AI terminal:

testkube_list_tests

List available tests and workflows from Testkube.

Parameters:

• type: test | workflow | all (default: all)
• namespace: Kubernetes namespace filter (optional)
• limit: Maximum tests to return (default: 50)

Example:

What tests are available in Testkube?
List all workflow tests in the staging namespace

testkube_run_test

Trigger a test or workflow execution.

Parameters:

• test_name (required): Name of the test/workflow to run
• namespace: Kubernetes namespace (optional)
• variables: Execution variables as key-value object (optional)
• sync_to_bugboard: Sync results to BugBoard (default: true)

Example:

Run the e2e-login test
Execute checkout-flow workflow with variable API_URL=https://staging.example.com

testkube_get_execution

Get status and details of a test execution.

Parameters:

• execution_id (required): Testkube execution ID
• include_artifacts: Include artifact list (default: false)

Example:

What's the status of execution abc123?
Show me the details of that test run including artifacts

testkube_list_executions

List recent test executions.

Parameters:

• test_name: Filter by test name (optional)
• status: running | passed | failed | aborted (optional)
• limit: Maximum executions to return (default: 20)

Example:

Show me the last 10 test runs
What tests failed recently?

testkube_get_artifacts

Get logs, screenshots, and reports from an execution.

Parameters:

• execution_id (required): Testkube execution ID
• artifact_name: Specific artifact to retrieve (optional)

Example:

What artifacts are available for execution abc123?
Show me the test-output.log from that execution

testkube_abort_execution

Stop a running test execution.

Parameters:

• execution_id (required): Testkube execution ID to abort

Example:

Stop the running test abc123
Abort that execution

Testkube Setup

1. Get your Testkube API credentials:

   • OSS/Self-hosted: Use your cluster's Testkube API endpoint
   • Control Plane: Get API token from app.testkube.io

2. Add to your MCP configuration:

{
  "mcpServers": {
    "bugboard": {
      "command": "npx",
      "args": ["@betterqa/bugboard-mcp"],
      "env": {
        "BUGBOARD_API_KEY": "your-bugboard-key",
        "TESTKUBE_URL": "https://api.testkube.io",
        "TESTKUBE_TOKEN": "your-testkube-token",
        "TESTKUBE_ORG": "your-org",
        "TESTKUBE_ENV": "your-env"
      }
    }
  }
}

3. Optionally configure webhook sync in BugBoard:
   • Go to Project Settings > Integrations > Testkube
   • Add your Testkube URL and API token
   • Configure which test suite receives results

Usage examples

Creating a bug while debugging

When you encounter a bug during development:

Claude, I found a bug - the user profile page crashes when the bio field is empty.
Can you create a bug for this?

Claude will use the create_bug tool to file the bug automatically.

Checking bug status

What bugs are currently in progress?

Claude will use list_bugs with status filter.

Updating bug status after fixing

I just fixed the profile crash bug. Mark BUG-000789 as fixed.

Claude will use update_bug to change the status.

Development

# Clone and install
git clone https://github.com/ArtificialHuman-ai/BugBoard.git
cd BugBoard/packages/mcp-server
npm install

# Build
npm run build

# Run locally
BUGBOARD_API_KEY=your-key npm start

License

MIT