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

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