BugHerd MCP Server

1# BugHerd MCP Server
2 
3An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that integrates [BugHerd](https://bugherd.com) bug tracking with AI assistants.
4 
5## Features
6 
7**Complete BugHerd API v2 coverage** with 38 tools across all resource types:
8 
9- **Organization** - Get account details
10- **Users** - List members, guests, user tasks and projects
11- **Projects** - CRUD operations, manage members and guests
12- **Tasks** - Full task management including feedback, archived, and taskboard views
13- **Columns** - Custom Kanban board management
14- **Comments** - Read and create comments
15- **Attachments** - Manage file attachments
16- **Webhooks** - Configure event notifications
17 
18## Installation
19 
20### Prerequisites
21 
22- Node.js 18+ or Bun
23- A BugHerd account with API access
24- BugHerd API key (get it from Settings > General Settings)
25 
26### Setup
27 
281. Clone the repository:
29 
30```bash
31git clone https://github.com/berckan/bugherd-mcp.git
32cd bugherd-mcp
33```
34 
352. Install dependencies:
36 
37```bash
38bun install
39# or
40npm install
41```
42 
433. Build the server:
44 
45```bash
46bun run build
47# or
48npm run build
49```
50 
514. Set your API key:
52 
53```bash
54export BUGHERD_API_KEY=your-api-key-here
55```
56 
57## Configuration
58 
59### CLI Configuration
60 
61Add to your MCP client config:
62 
63```json
64{
65  "mcpServers": {
66    "bugherd": {
67      "type": "stdio",
68      "command": "node",
69      "args": ["/path/to/bugherd-mcp/dist/index.js"],
70      "env": {
71        "BUGHERD_API_KEY": "your-api-key-here"
72      }
73    }
74  }
75}
76```
77 
78### Desktop Apps
79 
80Add to your MCP desktop app config:
81 
82```json
83{
84  "mcpServers": {
85    "bugherd": {
86      "command": "node",
87      "args": ["/path/to/bugherd-mcp/dist/index.js"],
88      "env": {
89        "BUGHERD_API_KEY": "your-api-key-here"
90      }
91    }
92  }
93}
94```
95 
96## Available Tools (37)
97 
98### Organization
99 
100| Tool                       | Description                      |
101| -------------------------- | -------------------------------- |
102| `bugherd_get_organization` | Get organization/account details |
103 
104### Users
105 
106| Tool                        | Description                       |
107| --------------------------- | --------------------------------- |
108| `bugherd_list_users`        | List all users (members + guests) |
109| `bugherd_list_members`      | List only team members            |
110| `bugherd_list_guests`       | List only guests/clients          |
111| `bugherd_get_user_tasks`    | Get tasks assigned to a user      |
112| `bugherd_get_user_projects` | Get projects for a user           |
113 
114### Projects
115 
116| Tool                           | Description                     |
117| ------------------------------ | ------------------------------- |
118| `bugherd_list_projects`        | List all projects               |
119| `bugherd_list_active_projects` | List only active projects       |
120| `bugherd_get_project`          | Get project details             |
121| `bugherd_create_project`       | Create a new project            |
122| `bugherd_update_project`       | Update project settings         |
123| `bugherd_delete_project`       | ⚠️ Delete a project permanently |
124| `bugherd_add_member`           | Add a member to a project       |
125| `bugherd_add_guest`            | Add a guest to a project        |
126 
127### Tasks
128 
129| Tool                           | Description                                     |
130| ------------------------------ | ----------------------------------------------- |
131| `bugherd_list_tasks`           | List tasks with filters (status, priority, tag) |
132| `bugherd_list_feedback_tasks`  | List unprocessed feedback tasks                 |
133| `bugherd_list_archived_tasks`  | List archived tasks                             |
134| `bugherd_list_taskboard_tasks` | List taskboard tasks                            |
135| `bugherd_get_task`             | Get task details with metadata                  |
136| `bugherd_get_task_global`      | Get task by global ID                           |
137| `bugherd_get_task_by_local_id` | Get task by local ID (#123)                     |
138| `bugherd_create_task`          | Create a new task                               |
139| `bugherd_move_tasks`           | Move tasks between projects                     |
140| `bugherd_update_task`          | Update task status/priority/description/assignee |
141 
142### Columns
143 
144| Tool                    | Description                            |
145| ----------------------- | -------------------------------------- |
146| `bugherd_list_columns`  | List project columns (Kanban statuses) |
147| `bugherd_get_column`    | Get column details                     |
148| `bugherd_create_column` | Create a new column                    |
149| `bugherd_update_column` | Update column name/position            |
150 
151### Comments
152 
153| Tool                     | Description             |
154| ------------------------ | ----------------------- |
155| `bugherd_list_comments`  | List comments on a task |
156| `bugherd_create_comment` | Add a comment to a task |
157 
158### Attachments
159 
160| Tool                        | Description                |
161| --------------------------- | -------------------------- |
162| `bugherd_list_attachments`  | List task attachments      |
163| `bugherd_get_attachment`    | Get attachment details     |
164| `bugherd_create_attachment` | Create attachment from URL |
165| `bugherd_delete_attachment` | ⚠️ Delete an attachment    |
166 
167### Webhooks
168 
169| Tool                     | Description              |
170| ------------------------ | ------------------------ |
171| `bugherd_list_webhooks`  | List configured webhooks |
172| `bugherd_create_webhook` | Create a webhook         |
173| `bugherd_delete_webhook` | ⚠️ Delete a webhook      |
174 
175## Usage Examples
176 
177### List projects and tasks
178 
179```
180List my BugHerd projects
181Show me all critical bugs in project 12345
182```
183 
184### Create and manage tasks
185 
186```
187Create a task in project 12345: "Fix the login button alignment"
188Move task 678 from project 12345 to project 67890
189Update task 678 status to "done"
190```
191 
192### Work with comments
193 
194```
195Show comments on task 678 in project 12345
196Add a comment to task 678: "Fixed in latest deploy"
197```
198 
199### Manage webhooks
200 
201```
202List all webhooks
203Create a webhook for task_create events pointing to https://example.com/webhook
204```
205 
206## Development
207 
208### Run in development mode:
209 
210```bash
211bun run dev
212```
213 
214### Test with MCP Inspector:
215 
216```bash
217BUGHERD_API_KEY=xxx bun run inspector
218```
219 
220### Build for production:
221 
222```bash
223bun run build
224```
225 
226## API Rate Limits
227 
228BugHerd allows an average of 60 requests per minute with bursts of up to 10 in quick succession. The server handles rate limiting errors gracefully.
229 
230## License
231 
232MIT
233 
234## Author
235 
236[Berckan Guerrero](https://github.com/berckan) (hi@berck.io)
237 
238## Contributing
239 
240Contributions are welcome! Please open an issue or submit a pull request.
241 
242## Related
243 
244- [BugHerd API Documentation](https://www.bugherd.com/api_v2)
245- [Model Context Protocol](https://modelcontextprotocol.io/)
246- [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)
247