@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 Claude Code

Add the MCP server to your Claude Code settings (~/.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"
      }
    }
  }
}

3. Restart Claude Code

After updating settings, restart Claude Code 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) |

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