Laravel Forge MCP

A native Laravel MCP server for managing Laravel Forge servers, sites and deployments. It is a Composer-installable replacement for the Node @bretterer/forge-mcp-server package and talks to the Forge API v2 through the official laravel/forge-sdk.

Contents

• Requirements
• Installation
• Configuration
  • API token
  • Organization slug
• Usage
• Tools
• Testing
• Contributing
• License

Requirements

• PHP 8.2+
• Laravel 12 or 13
• laravel/mcp ^0.7
• A Laravel Forge API v2 token (see API token)

Installation

composer require isapp/laravel-forge-mcp

The service provider is auto-discovered.

Configuration

The package reuses the standard laravel/forge-sdk configuration. Add a forge entry to config/services.php:

'forge' => [
    'token' => env('FORGE_API_TOKEN'),
    // Optional. Forge API v2 scopes calls to an organization. Leave this out
    // to resolve it automatically; set it when the token can access more than
    // one organization.
    'organization' => env('FORGE_ORG_SLUG'),
],

FORGE_API_TOKEN=your-forge-api-token
# FORGE_ORG_SLUG=your-org-slug

API token

This package talks to the organization-scoped Forge API v2. To create a token:

1. Open your Forge account dashboard and click API.
2. Click Create token, give it a name and an optional expiration date.
3. Select the scopes the token should have, then click Add token.
4. Copy the generated token into FORGE_API_TOKEN.

Scopes. Forge lets you restrict a token to specific scopes. This package needs only the following:

If you only use the read-only tools, server:view is enough (plus organization:view when the slug is auto-resolved). You do not need server:manage-logs — that scope only clears logs, while this server only reads them. A token missing a required scope makes the corresponding tool return a Forge authorization error.

The legacy Forge API v1 is being retired (scheduled 30 June 2026). This package only uses API v2, so create the token from the current dashboard as described above.

Organization slug

Forge API v2 requires an organization slug on every server and site call. When services.forge.organization is empty the package resolves it automatically:

• exactly one organization on the token → it is used and cached;
• multiple organizations → set FORGE_ORG_SLUG, or pass organizationSlug to an individual tool call.

Usage

The package registers a local (stdio) MCP server named forge. Start it with:

php artisan mcp:start forge

Point your MCP client at that command. For example, in a .mcp.json:

{
    "mcpServers": {
        "forge": {
            "command": "php",
            "args": ["artisan", "mcp:start", "forge"]
        }
    }
}

Inspect it interactively with:

php artisan mcp:inspector forge

Tools

Every tool accepts an optional organizationSlug argument to override the resolved organization for that call.

Forge API v2 note: the old API v1 server load and reset deployment state endpoints do not exist in API v2 and are intentionally not provided.

Testing

composer test       # run the test suite
composer lint       # apply coding standards (Laravel Pint)
composer lint:test  # check coding standards without modifying files

Contributing

See AGENTS.md for architecture, conventions and how to add a tool. Pull requests run the test matrix (PHP 8.2–8.4 × Laravel 12–13) and Pint via GitHub Actions.

License

The MIT License (MIT). See LICENSE.