laravel-forge-mcp

An MCP server that helps agents manage Laravel Forge servers, sites, and deployments through the Laravel Forge API.

This server lets MCP clients (for example Claude, Cline, Cursor, or Codex) easily:

• list Forge managed servers,
• inspect sites on a server,
• search sites before choosing a deployment target,
• trigger a Forge deployment for a site,
• reset a stuck deployment status,
• read deployment history, deployment output, current deployment log, and deployment script.

Features

• Communicates with the Laravel Forge API using a token passed by --api-key.
• Tools:
  • forge_list_servers
  • forge_get_server
  • forge_list_sites
  • forge_get_site
  • forge_find_sites
  • forge_deploy_site
  • forge_reset_deployment_status
  • forge_list_deployments
  • forge_get_deployment
  • forge_get_deployment_log
  • forge_get_deployment_output
  • forge_get_deployment_script
• Local pagination for list/search tools.
• Markdown and JSON response formats for structured data tools.
• Actionable Forge API error messages for authentication, missing resources, rate limits, and server errors.
• Covered by tests (vitest).

Requirements

• Node.js 18+
• npm
• Laravel Forge API token

Running

The server uses stdio MCP transport, so your MCP client should launch it with:

npx -y laravel-forge-mcp@latest --api-key your-forge-api-token

Claude Code example

{
  "mcpServers": {
    "laravel-forge": {
      "command": "npx",
      "args": ["-y", "laravel-forge-mcp@latest", "--api-key", "your-forge-api-token"]
    }
  }
}

Cursor example

{
  "mcpServers": {
    "laravel-forge": {
      "command": "npx",
      "args": ["-y", "laravel-forge-mcp@latest", "--api-key", "your-forge-api-token"]
    }
  }
}

Codex-style TOML example:

[mcp_servers.laravel-forge]
command = "npx"
args = ["-y", "laravel-forge-mcp@latest", "--api-key", "your-forge-api-token"]
startup_timeout_sec = 20.0

Development

Run tests:

npm test

Run tests with coverage:

npm run test:coverage

Watch mode:

npm run test:watch

Run locally from this repository:

npm start -- --api-key your-forge-api-token

Project Structure

• index.js: CLI bootstrap entrypoint.
• src/cli.js: command argument parsing.
• src/forge.js: Laravel Forge API client and error handling.
• src/server.js: MCP server creation and tool registration.
• tests/cli.unit.test.mjs: CLI parser tests.
• tests/forge.unit.test.mjs: Forge API client tests.
• tests/server.integration.test.mjs: MCP server integration tests.

License

• Project: MIT