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

{
  "mcp": {
    "servers": {
      "laravel-herd": {
        "type": "stdio",
        "command": "npx",
        "args": ["-y", "laravel-herd-mcp"]
      }
    }
  }
}

5 — Reload: Ctrl+Shift+P → Developer: Reload Window

6 — Verify: Ctrl+Alt+I → Copilot Chat → Agent tab → Tools icon (🔌) → laravel-herd should appear.

7 — MCP Servers panel tabs (Configuration / Details / Manifest)

VS Code starts MCP servers lazily — it only connects on the first tool call. Until then the panel shows only the Configuration tab.

• Configuration — always visible (your settings.json snippet)
• Details — appears after first connection: server name Laravel Herd, version, description, homepage
• Manifest — appears after first connection: all 218 tools with names and descriptions

To unlock Details + Manifest immediately: open Copilot Chat → Agent mode → use any laravel-herd tool (e.g. "list herd sites") → accept the permission prompt → return to the MCP panel.

Alternative — SSE mode (all tabs visible immediately, no tool use required)

# Step 1: start the server persistently (add to startup / Task Scheduler)
npx laravel-herd-mcp --http --port 3333

// Step 2: use SSE transport in settings.json instead of stdio
{
  "mcp": {
    "servers": {
      "laravel-herd": {
        "type": "sse",
        "url": "http://localhost:3333/sse"
      }
    }
  }
}

VS Code connects to the SSE endpoint on startup — all three tabs are populated immediately.

Cursor

Create or edit ~/.cursor/mcp.json:

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

Restart Cursor → check Cursor Settings → MCP.

Windsurf (Codeium)

Create or edit ~/.codeium/windsurf/mcp_config.json:

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

Zed

Edit ~/.config/zed/settings.json:

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

OpenAI Codex CLI

Append to ~/.codex/config.toml:

[[mcp_servers]]
name = "laravel-herd"
command = "npx"
args = ["-y", "laravel-herd-mcp"]

Antigravity

Edit %USERPROFILE%\.gemini\antigravity\mcp_config.json (macOS: ~/.gemini/antigravity/mcp_config.json).

Merge laravel-herd into the existing mcpServers object — do not add a second {...} block:

{
  "mcpServers": {
    "context7": {
      "serverUrl": "https://mcp.context7.com/mcp",
      "headers": { "CONTEXT7_API_KEY": "your-key" }
    },
    "laravel-herd": {
      "command": "npx",
      "args": ["-y", "laravel-herd-mcp"]
    }
  }
}

PhpStorm / JetBrains IDEs

1. Open Settings (Ctrl+Alt+S)
2. Navigate to Tools → AI Assistant → Model Context Protocol (MCP)
3. Click + → As Process
4. Command: npx — Arguments: -y laravel-herd-mcp
5. Click Apply → restart the IDE

See install-mcp-wizard/configs/phpstorm.xml for the XML snippet.

Other MCP clients

Any client that supports MCP stdio transport:

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

Check your client's documentation for the config file location and format. See install-mcp-wizard/configs/generic.json.

Custom Herd path

If Herd is installed in a non-default location, pass HERD_PATH:

{
  "mcpServers": {
    "laravel-herd": {
      "command": "npx",
      "args": ["laravel-herd-mcp"],
      "env": {
        "HERD_PATH": "C:\\Users\\YourUser\\.config\\herd\\bin"
      }
    }
  }
}

Auto-configure (using the tool itself)

Once running, ask Claude to run setup_integrations — it will write the correct config to Claude Desktop, Claude Code, and Herd's integrations.json automatically.

---

HTTP / SSE Mode

Run as a persistent HTTP server for multi-client or custom integrations:

npx laravel-herd-mcp --http --port 3333

Connect your MCP client to http://localhost:3333/sse.

---

Available Tools

218 tools in a single laravel-herd MCP server. 📄 Full tool reference → tools.md

Category	Tools	Description
Active Project	3	Select active site — all tools default to it without explicit cwd
Herd Control	8	Start/stop/restart, loopback, Herd manifest
Sites	16	Park, link, proxy, share, browser, IDE
SSL / HTTPS	3	Secure, unsecure, list certs
PHP	9	Versions, isolation, php.ini
Node / NVM	3	Install, list, switch Node versions
Services	8	MySQL, Redis, PostgreSQL, Minio (Herd Pro)
Database (artisan)	8	.env info, GUI client, db:show, db:table, wipe, seed, monitor, db CLI
Laravel Debugbar	9	Install, enable/disable, read queries/exceptions/timeline (fruitcake/laravel-debugbar)
Direct Database Client	7	Native SQL queries for MySQL, MariaDB, PostgreSQL, SQLite — local or remote
Cache	14	App cache, config, view, route, event cache
Queue & Schedule	19	Failed jobs, active queue, batches, schedule, Horizon
Dumps & Debugging	12	Herd interceptor, watchers, Xdebug, Ray, Clockwork
Laravel Telescope	19	Install, enable/disable, watchers, all 18 entry-type browsers (laravel/telescope)
Laravel Pulse	14	Install, enable/disable, server metrics, slow requests/queries/jobs, exceptions, cache, queues, users (laravel/pulse)
Laravel Nightwatch	7	Install, enable/disable, agent start/stop, configure sampling (laravel/nightwatch)
Artisan	10	Generic + make:*, migrate, routes, optimize, seed
Composer	12	require, remove, install, update, search, scripts
Laravel Boost	5	AI coding guidelines (laravel/boost)
Laravel Forge CLI	25	Remote server management: deploy, env, daemons, nginx, php (forge CLI)
Setup & Integration	3	Auto-configure Claude Desktop + Claude Code + Herd

---

Configuration

Environment variables

Variable	Default	Description
HERD_PATH	auto-detected	Path to Herd's bin directory

CLI flags

Flag	Default	Description
--http	off	Run as HTTP/SSE server
--port N	3333	Port for HTTP/SSE mode
--herd-path PATH	auto-detected	Override Herd bin directory

Herd path auto-detection order

1. --herd-path CLI flag
2. HERD_PATH environment variable
3. %USERPROFILE%\.config\herd\bin\herd.bat
4. herd.bat on system PATH

---

Git Bash / MINGW

Add these aliases to ~/.bash_profile:

alias php="php.bat"
alias herd="herd.bat"
alias laravel="laravel.bat"
alias composer="composer.bat"

---

How It Works

laravel-herd-mcp talks to Herd through two channels:

Claude ──► laravel-herd-mcp ──► Herd HTTP API (127.0.0.1:9001)   — structured JSON
                             └──► PHP CLI (php.exe herd.phar …)   — park, link, proxy, share…
                             └──► php artisan                     — migrate, queue, cache…
                             └──► composer                        — require, install, update…
                             └──► Herd config.json                — dumps, watchers, settings
                             └──► Native DB drivers               — mysql2, pg, better-sqlite3
                             └──► storage/debugbar/*.json         — Debugbar request profiling
                             └──► telescope_entries DB table      — Telescope watcher data
                             └──► pulse_* DB tables              — Pulse performance metrics

Non-ASCII path fix: herd.bat calls bare php which breaks when the Windows user profile path contains non-ASCII characters (e.g. Cyrillic). This package bypasses herd.bat entirely and calls php.exe herd.phar directly, resolving the PHP executable from Herd's own config.json.

---

Comparison with herd-mcp.phar

Laravel Herd ships a built-in herd-mcp.phar (PHP, stdio only). laravel-herd-mcp extends and complements it:

Feature	herd-mcp.phar	laravel-herd-mcp
Stdio transport	✅	✅
HTTP / SSE transport	❌	✅
Sites, PHP versions	✅	✅
Debug sessions (Pro)	✅	✅
Forge integration	✅	❌
Park / unpark / link	❌	✅
Proxy management	❌	✅
SSL management	❌	✅
Herd start / stop / restart	❌	✅
Site sharing (Expose)	❌	✅
Log tailing	❌	✅
Node.js / NVM	❌	✅
php artisan commands	❌	✅
Composer commands	❌	✅
Database tools	❌	✅
Cache management	❌	✅
Queue & Schedule	❌	✅
Dump interceptor / watchers	❌	✅
Ray / Telescope / Clockwork	❌	✅
Laravel Pulse / Nightwatch	❌	✅
Laravel Boost integration	❌	✅
Non-ASCII user profile paths	❌	✅

---

Herd UI Patching (patch_herd_ui)

As of v0.1.22 you no longer need patch_herd_ui.

The patch_herd_ui tool patches Herd's app.asar to add a Claude Code row in the Integrations tab. This was needed in early versions to get the MCP entry visible inside Herd's UI. Since v0.1.22:

• The setup_integrations tool writes the correct config to Claude Desktop and Claude Code directly — no UI patching needed.
• Herd's own integration support has improved and the entry is visible without patching.

patch_herd_ui is kept in the plugin for educational purposes only — it demonstrates how Electron app.asar files can be extracted and repackaged. Do not run it on production Herd installations as it must be re-applied after every Herd update.

---

Contributing

Contributions welcome! Open an issue or pull request.

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

---

License

MIT — see LICENSE

---

Related

This project

Resource	Link
GitHub repository	github.com/movinginfo/laravel-herd-mcp
npm package	npmjs.com/package/laravel-herd-mcp
Tool reference	tools.md — all 218 tools across 20 categories
MCP install wizard	install-mcp-wizard/README.md

Core

Repo / Project	Role
laravel/herd	The PHP development environment this server controls
@modelcontextprotocol/sdk · modelcontextprotocol.io	MCP SDK and protocol spec

Supported AI clients

Client	Docs
Claude Desktop	Anthropic desktop app — stdio MCP
Claude Code	Anthropic CLI — claude mcp add
VS Code + GitHub Copilot	settings.json mcp.servers
Cursor	~/.cursor/mcp.json
Windsurf (Codeium)	~/.codeium/windsurf/mcp_config.json
Zed	~/.config/zed/settings.json context_servers
PhpStorm / JetBrains	Settings → AI Assistant → MCP
Antigravity	~/.antigravity/mcp.json
OpenAI Codex CLI	~/.codex/config.toml

Laravel packages integrated

Package	Tools
laravel/telescope	telescope_* — 19 tools: requests, queries, exceptions, jobs, mail, events…
laravel/pulse	pulse_* — 14 tools: slow requests/queries/jobs, exceptions, cache, servers…
laravel/nightwatch	nightwatch_* — 7 tools: install, agent start/stop, enable/disable, configure
laravel/horizon	horizon_* — status, pause, continue, terminate
laravel/boost	boost_* — AI coding guidelines, MCP config
laravel/forge-cli	forge_* — 25 tools: deploy, env, daemons, nginx, php-fpm
fruitcake/laravel-debugbar	debugbar_* — 9 tools: requests, queries, exceptions, timeline
spatie/laravel-ray	ray_* — install, configure
itsgoingd/clockwork	clockwork_install

Node.js drivers (direct DB access)

Package	Purpose
mysql2	MySQL / MariaDB native driver — no PHP needed
pg	PostgreSQL native driver
better-sqlite3	SQLite native driver (optional)

Transport & schema

Package	Purpose
@modelcontextprotocol/sdk	MCP server SDK (stdio + HTTP/SSE)
express	HTTP server for --http / SSE mode
zod	Runtime schema validation for all tool inputs