laravel-herd-mcp

laravel-herd-mcp

218 MCP tools — Give Claude full control over your Laravel Herd development environment on Windows.

---

What is this?

laravel-herd-mcp connects Claude Desktop (or any MCP client) to your local Laravel Herd installation. Once configured, you can manage your entire PHP development environment through natural language — no terminal required.

"Create a new Laravel project called blog, park it, secure it with HTTPS, and isolate it to PHP 8.3"
"Show me failed queue jobs and retry them all"
"Run the database migrations and seed the users table"
"Which sites are running? Switch my-app to PHP 8.2 and restart Herd"
"Install Laravel Telescope and clear its entries older than 24 hours"
"Enable the queries and events watchers in Herd"

This server complements Herd's built-in herd-mcp.phar by adding HTTP/SSE transport, full CLI tool coverage, artisan commands, composer management, debugging tools, and more.

---

Features

• 218 MCP tools across 20 categories — see full list →
• Multi-IDE — Claude Desktop, Claude Code, VS Code (Copilot/Continue), Cursor, Windsurf, PhpStorm, and any MCP-compatible client
• Cross-platform — Windows and macOS both supported; Herd paths auto-detected on both
• Dual transport — stdio for local clients, HTTP/SSE for remote or multi-client setups
• Auto-detects your Herd installation, no manual path configuration needed
• Herd Free + Pro — all Pro-only features degrade gracefully with clear messages
• Non-ASCII paths — works correctly even if your Windows username contains Cyrillic or other non-ASCII characters
• Structured output — clean JSON from the Herd API, ANSI codes stripped from CLI output

---

Requirements

Laravel Herd	v1.27+ for Windows · v1.0+ for macOS
Node.js	18+
MCP client	Claude Desktop or any MCP-compatible client

macOS: Fully supported. Laravel Herd stores its config at ~/.config/herd/ and ~/Library/Application Support/Herd/ — both paths are auto-detected.

---

Installation

Option A — npx (no install required)

npx laravel-herd-mcp

Option B — Global install

npm install -g laravel-herd-mcp
laravel-herd-mcp

Option C — Local build from source

git clone https://github.com/movinginfo/laravel-herd-mcp
cd laravel-herd-mcp
npm install && npm run build
node dist/index.js

---

Setup

Auto-installer (all IDEs in one command)

Detect and configure every supported IDE automatically:

node install-mcp-wizard/install.js

The wizard detects Claude Desktop, Claude Code, VS Code, Cursor, Windsurf, Zed, Codex CLI, Antigravity, and PhpStorm — backs up existing configs and merges the MCP entry.

# Options:
node install-mcp-wizard/install.js --yes      # skip confirmation
node install-mcp-wizard/install.js --list     # show detected IDEs only
node install-mcp-wizard/install.js --dry-run  # preview changes, write nothing

📄 Full per-IDE instructions → install-mcp-wizard/README.md

---

Claude Desktop

Edit %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "laravel-herd": {
      "command": "npx",
      "args": ["-y", "laravel-herd-mcp"]
    }
  }
}

Restart Claude Desktop.

Claude Code

claude mcp add laravel-herd -- npx -y laravel-herd-mcp

Or edit ~/.claude/settings.json directly with the same mcpServers block above.

VS Code

Requires VS Code 1.99+ and the GitHub Copilot extension.

1 — Install Copilot: Ctrl+Shift+X → search GitHub Copilot → Install → sign in.

2 — Enable agent mode: Ctrl+, → search chat.agent.enabled → tick checkbox.

3 — Open settings.json:

• Ctrl+Shift+P → Preferences: Open User Settings (JSON) (include the Preferences: prefix)
• Or navigate directly:
  • Windows: %APPDATA%\Code\User\settings.json
  • macOS: ~/Library/Application Support/Code/User/settings.json
  • Linux: ~/.config/Code/User/settings.json

4 — Add the MCP block (merge — do not replace the whole file):