# Berckan/bugherd-mcp [Health: Active]

**Category:** 🎧 Support & Service Management  
**Repository:** https://github.com/Berckan/bugherd-mcp  
**GitHub Stars:** 7  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/berckan-bugherd-mcp

## Description
MCP server for BugHerd bug tracking. List projects, view tasks with filtering by status/priority/tags, get task details, and read comments.

## Tools
Capabilities this server exposes over MCP:

- **bugherd_get_organization** — Get organization/account details
- **bugherd_list_users** — List all users (members + guests)
- **bugherd_list_members** — List only team members
- **bugherd_list_guests** — List only guests/clients
- **bugherd_get_user_tasks** — Get tasks assigned to a user
- **bugherd_get_user_projects** — Get projects for a user
- **bugherd_list_projects** — List all projects
- **bugherd_list_active_projects** — List only active projects
- **bugherd_get_project** — Get project details
- **bugherd_create_project** — Create a new project
- **bugherd_update_project** — Update project settings
- **bugherd_delete_project** — ⚠️ Delete a project permanently
- **bugherd_add_member** — Add a member to a project
- **bugherd_add_guest** — Add a guest to a project
- **bugherd_list_tasks** — List tasks with filters (status, priority, tag)
- **bugherd_list_feedback_tasks** — List unprocessed feedback tasks
- **bugherd_list_archived_tasks** — List archived tasks
- **bugherd_list_taskboard_tasks** — List taskboard tasks
- **bugherd_get_task** — Get task details with metadata
- **bugherd_get_task_global** — Get task by global ID
- **bugherd_get_task_by_local_id** — Get task by local ID (#123)
- **bugherd_create_task** — Create a new task
- **bugherd_move_tasks** — Move tasks between projects
- **bugherd_update_task** — Update task status/priority/description/assignee
- **bugherd_list_columns** — List project columns (Kanban statuses)
- **bugherd_get_column** — Get column details
- **bugherd_create_column** — Create a new column
- **bugherd_update_column** — Update column name/position
- **bugherd_list_comments** — List comments on a task
- **bugherd_create_comment** — Add a comment to a task
- **bugherd_list_attachments** — List task attachments
- **bugherd_get_attachment** — Get attachment details
- **bugherd_create_attachment** — Create attachment from URL
- **bugherd_delete_attachment** — ⚠️ Delete an attachment
- **bugherd_list_webhooks** — List configured webhooks
- **bugherd_create_webhook** — Create a webhook
- **bugherd_delete_webhook** — ⚠️ Delete a webhook

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "bugherd-mcp": {
    "command": "npx",
    "args": ["-y","berckan-bugherd-mcp"]
  }
}
```

## Documentation & README

# 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](https://github.com/macropodhq/bugherd-mcp).

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that integrates [BugHerd](https://bugherd.com) 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:

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

2. Install dependencies:

```bash
bun install
# or
npm install
```

3. Build the server:

```bash
bun run build
# or
npm run build
```

4. Set your API key:

```bash
export BUGHERD_API_KEY=your-api-key-here
```

## Configuration

### CLI Configuration

Add to your MCP client config:

```json
{
  "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:

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

## Available Tools (37)

### Organization

| Tool                       | Description                      |
| -------------------------- | -------------------------------- |
| `bugherd_get_organization` | Get organization/account details |

### Users

| Tool                        | Description                       |
| --------------------------- | --------------------------------- |
| `bugherd_list_users`        | List all users (members + guests) |
| `bugherd_list_members`      | List only team members            |
| `bugherd_list_guests`       | List only guests/clients          |
| `bugherd_get_user_tasks`    | Get tasks assigned to a user      |
| `bugherd_get_user_projects` | Get projects for a user           |

### Projects

| Tool                           | Description                     |
| ------------------------------ | ------------------------------- |
| `bugherd_list_projects`        | List all projects               |
| `bugherd_list_active_projects` | List only active projects       |
| `bugherd_get_project`          | Get project details             |
| `bugherd_create_project`       | Create a new project            |
| `bugherd_update_project`       | Update project settings         |
| `bugherd_delete_project`       | ⚠️ Delete a project permanently |
| `bugherd_add_member`           | Add a member to a project       |
| `bugherd_add_guest`            | Add a guest to a project        |

### Tasks

| Tool                           | Description                                      |
| ------------------------------ | ------------------------------------------------ |
| `bugherd_list_tasks`           | List tasks with filters (status, priority, tag)  |
| `bugherd_list_feedback_tasks`  | List unprocessed feedback tasks                  |
| `bugherd_list_archived_tasks`  | List archived tasks                              |
| `bugherd_list_taskboard_tasks` | List taskboard tasks                             |
| `bugherd_get_task`             | Get task details with metadata                   |
| `bugherd_get_task_global`      | Get task by global ID                            |
| `bugherd_get_task_by_local_id` | Get task by local ID (#123)                      |
| `bugherd_create_task`          | Create a new task                                |
| `bugherd_move_tasks`           | Move tasks between projects                      |
| `bugherd_update_task`          | Update task status/priority/description/assignee |

### Columns

| Tool                    | Description                            |
| ----------------------- | -------------------------------------- |
| `bugherd_list_columns`  | List project columns (Kanban statuses) |
| `bugherd_get_column`    | Get column details                     |
| `bugherd_create_column` | Create a new column                    |
| `bugherd_update_column` | Update column name/position            |

### Comments

| Tool                     | Description             |
| ------------------------ | ----------------------- |
| `bugherd_list_comments`  | List comments on a task |
| `bugherd_create_comment` | Add a comment to a task |

### Attachments

| Tool                        | Description                |
| --------------------------- | -------------------------- |
| `bugherd_list_attachments`  | List task attachments      |
| `bugherd_get_attachment`    | Get attachment details     |
| `bugherd_create_attachment` | Create attachment from URL |
| `bugherd_delete_attachment` | ⚠️ Delete an attachment    |

### Webhooks

| Tool                     | Description              |
| ------------------------ | ------------------------ |
| `bugherd_list_webhooks`  | List configured webhooks |
| `bugherd_create_webhook` | Create a webhook         |
| `bugherd_delete_webhook` | ⚠️ Delete a webhook      |

## 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:

```bash
bun run dev
```

### Test with MCP Inspector:

```bash
BUGHERD_API_KEY=xxx bun run inspector
```

### Build for production:

```bash
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](https://github.com/berckan)

## Contributing

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

## Related

- [BugHerd API Documentation](https://www.bugherd.com/api_v2)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)