leapfinder/laravel-bugherd-mcp

Laravel MCP server for the BugHerd API v2

v1.0.0 2026-03-06 03:32 UTC

Requires

• php: ^8.2
• illuminate/http: ^11.0|^12.0
• illuminate/support: ^11.0|^12.0
• laravel/mcp: ^0.6

Requires (Dev)

• laravel/boost: ^2.2
• orchestra/testbench: ^9.0|^10.0
• phpunit/phpunit: ^11.0
• spatie/boost-spatie-guidelines: ^1.0

MIT

• LeapFinder

• bugherd
• laravel
• mcp
• bug-tracking

README

A read-only MCP server for the BugHerd API v2. Browse projects, review tasks, and read discussion threads from any MCP-compatible client.

Built with Laravel MCP.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• laravel/mcp ^0.6
• A BugHerd API key

Installation

composer require leapfinder/laravel-bugherd-mcp

The service provider is auto-discovered. To publish the config file (optional):

php artisan vendor:publish --tag=bugherd-mcp-config

Add your BugHerd API key to .env:

BUGHERD_API_KEY=your_api_key_here

Getting your API key

In BugHerd, go to Settings > General Settings. Your API key is listed there. The key authenticates via HTTP Basic Auth (key as username, x as password). All requests use HTTPS.

MCP Client Setup

Start the MCP server via Artisan:

php artisan mcp:start bugherd

The server communicates over stdio. Add it to your MCP client configuration - for example, in a .mcp.json file:

{
  "mcpServers": {
    "bugherd": {
      "type": "stdio",
      "command": "php",
      "args": ["artisan", "mcp:start", "bugherd"]
    }
  }
}

Available Tools

Tool	Description
bugherd_list_projects	List all projects, optionally filtered to active only
bugherd_show_project	Get full details for a specific project
bugherd_list_tasks	List tasks with filters (status, priority, tag, assignee, date range)
bugherd_show_task	Get full task details including metadata and screenshot URLs
bugherd_list_comments	Get the full discussion thread for a task
bugherd_list_columns	Get the kanban board column structure for a project

All tools are currently read-only. Results are paginated at 100 records per page.

BugHerd API Notes

• Rate limit: 60 requests/minute average, bursts of 10. The client retries automatically on 429 responses.
• Task statuses: backlog, todo, doing, done, closed, or custom column names.
• Task priorities: not set, critical, important, normal, minor.
• Pagination: Use the page parameter. Max 100 records per response.

Roadmap

v1.0 - Read-only tools (current)

• List and show projects
• List and show tasks (with filters)
• List comments
• List columns

Planned

• Create, update, and delete tasks
• Create comments
• List and manage users
• List and manage tags
• Webhook management
• Organization endpoints

Contributions welcome - see CONTRIBUTING.md.

License

MIT. See LICENSE.

Built by LeapFinder