io.github.Berckan/bugherd-mcp

BugHerd MCP Server

Note: This is an unofficial, community-maintained, open-source (MIT) BugHerd MCP server. It runs locally, your data never leaves your machine. For BugHerd's official closed-source hosted server, see macropodhq/bugherd-mcp.

An MCP (Model Context Protocol) server that integrates BugHerd bug tracking with AI assistants.

Features

Complete BugHerd API v2 coverage with 38 tools across all resource types:

• Organization - Get account details
• Users - List members, guests, user tasks and projects
• Projects - CRUD operations, manage members and guests
• Tasks - Full task management including feedback, archived, and taskboard views
• Columns - Custom Kanban board management
• Comments - Read and create comments
• Attachments - Manage file attachments
• Webhooks - Configure event notifications

Installation

Prerequisites

• Node.js 18+ or Bun
• A BugHerd account with API access
• BugHerd API key (get it from Settings > General Settings)

Setup

1. Clone the repository:

git clone https://github.com/berckan/bugherd-mcp.git
cd bugherd-mcp

1. Install dependencies:

bun install
# or
npm install

1. Build the server:

bun run build
# or
npm run build

1. Set your API key:

export BUGHERD_API_KEY=your-api-key-here

Configuration

CLI Configuration

Add to your MCP client config:

{
  "mcpServers": {
    "bugherd": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/bugherd-mcp/dist/index.js"],
      "env": {
        "BUGHERD_API_KEY": "your-api-key-here"
      }
    }
  }
}

Desktop Apps

Add to your MCP desktop app config:

{
  "mcpServers": {
    "bugherd": {
      "command": "node",
      "args": ["/path/to/bugherd-mcp/dist/index.js"],
      "env": {
        "BUGHERD_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools (37)

Organization

Users

Projects

Tasks

Columns

Comments

Attachments

Webhooks

Usage Examples

List projects and tasks

List my BugHerd projects
Show me all critical bugs in project 12345

Create and manage tasks

Create a task in project 12345: "Fix the login button alignment"
Move task 678 from project 12345 to project 67890
Update task 678 status to "done"

Work with comments

Show comments on task 678 in project 12345
Add a comment to task 678: "Fixed in latest deploy"

Manage webhooks

List all webhooks
Create a webhook for task_create events pointing to https://example.com/webhook

Development

Run in development mode:

bun run dev

Test with MCP Inspector:

BUGHERD_API_KEY=xxx bun run inspector

Build for production:

bun run build

API Rate Limits

BugHerd allows an average of 60 requests per minute with bursts of up to 10 in quick succession. The server handles rate limiting errors gracefully.

License

MIT

Author

Berckan Guerrero

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Related

• BugHerd API Documentation
• Model Context Protocol
• MCP TypeScript SDK