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.

Related MCP server: Universal Dev MCP

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

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

Configuration

Environment variables

CLI flags

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:

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

Core

Supported AI clients

Laravel packages integrated

Node.js drivers (direct DB access)

Transport & schema