PHPackages                             isapp/laravel-forge-mcp - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [DevOps & Deployment](/categories/devops)
4. /
5. isapp/laravel-forge-mcp

ActiveLibrary[DevOps & Deployment](/categories/devops)

isapp/laravel-forge-mcp
=======================

Native Laravel MCP server for managing Laravel Forge servers, sites and deployments via the Forge API v2.

v1.3.0(yesterday)010↑2600%[1 PRs](https://github.com/isap-ou/laravel-forge-mcp/pulls)MITPHPPHP ^8.2CI passing

Since Jun 8Pushed yesterdayCompare

[ Source](https://github.com/isap-ou/laravel-forge-mcp)[ Packagist](https://packagist.org/packages/isapp/laravel-forge-mcp)[ RSS](/packages/isapp-laravel-forge-mcp/feed)WikiDiscussions main Synced yesterday

READMEChangelog (4)Dependencies (8)Versions (6)Used By (0)

Laravel Forge MCP
=================

[](#laravel-forge-mcp)

[![Tests](https://github.com/isap-ou/laravel-forge-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/isap-ou/laravel-forge-mcp/actions/workflows/tests.yml)[![Lint](https://github.com/isap-ou/laravel-forge-mcp/actions/workflows/lint.yml/badge.svg)](https://github.com/isap-ou/laravel-forge-mcp/actions/workflows/lint.yml)[![Latest Version](https://camo.githubusercontent.com/86285443de4d6d5abb0294dabda5765951197ed15e1e4ddea6cfeedbe4f3aa75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f69736170702f6c61726176656c2d666f7267652d6d63702e737667)](https://packagist.org/packages/isapp/laravel-forge-mcp)[![PHP Version](https://camo.githubusercontent.com/1e1f2412791d2765d6fc885319ee8c90cbbd64b6bd93e0390f949687f7538199/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f646570656e64656e63792d762f69736170702f6c61726176656c2d666f7267652d6d63702f7068702e737667)](https://packagist.org/packages/isapp/laravel-forge-mcp)[![License](https://camo.githubusercontent.com/8865974220abb5542f0bfbe997e9a4dbe0ea3c39bc46d055307bda79608b7865/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f69736170702f6c61726176656c2d666f7267652d6d63702e737667)](LICENSE)

A native Laravel [MCP](https://github.com/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`](https://github.com/laravel/forge-sdk).

Contents
--------

[](#contents)

- [Requirements](#requirements)
- [Installation](#installation)
- [Configuration](#configuration)
    - [API token](#api-token)
    - [Organization slug](#organization-slug)
    - [Safety flags](#safety-flags)
- [Usage](#usage)
- [Tools](#tools)
- [Testing](#testing)
- [Contributing](#contributing)
- [License](#license)

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12 or 13
- `laravel/mcp` ^0.7
- A Laravel Forge **API v2** token (see [API token](#api-token))

Installation
------------

[](#installation)

```
composer require isapp/laravel-forge-mcp
```

The service provider is auto-discovered.

Configuration
-------------

[](#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'),

    // Optional safety/behaviour flags (all default to false):
    // Expose only read-only tools; deploy, reboot, deployment-script update
    // and quick-deploy toggle are not registered.
    'read_only' => env('FORGE_MCP_READ_ONLY', false),
    // Register the get_site_environment tool. It returns the site's .env
    // (secrets), so it is disabled unless you opt in.
    'expose_environment' => env('FORGE_MCP_EXPOSE_ENVIRONMENT', false),
    // Return raw Forge/SDK exception messages to the client. When false the
    // client gets a generic message and the full error goes to the log.
    'verbose_errors' => env('FORGE_MCP_VERBOSE_ERRORS', false),
],
```

```
FORGE_API_TOKEN=your-forge-api-token
# FORGE_ORG_SLUG=your-org-slug
# FORGE_MCP_READ_ONLY=true
# FORGE_MCP_EXPOSE_ENVIRONMENT=true
# FORGE_MCP_VERBOSE_ERRORS=true
```

### API token

[](#api-token)

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

1. Open your [Forge account dashboard](https://forge.laravel.com) 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:

ScopeUsed for`server:view`Reading servers, sites, deployments and logs (all the `list_*` / `get_*` tools).`site:manage-deploys``deploy_site`, `get_deployment_script`, `update_deployment_script`, `toggle_quick_deploy`.`server:manage-services``reboot_server`.`site:manage-environment``get_site_environment` (unverified — reading the env file may also be covered by `server:view`).`organization:view`Only when `FORGE_ORG_SLUG` is **not** set — the package lists your organizations to resolve the slug automatically. Not needed if you set the slug explicitly.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

[](#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.

### Safety flags

[](#safety-flags)

This server hands an AI agent control over your Forge infrastructure, so it ships with conservative defaults. All three flags live under `services.forge`and default to `false`:

- **`read_only`** — when `true`, only read-only tools are registered. The state-changing tools (`deploy_site`, `reboot_server`, `update_deployment_script`, `toggle_quick_deploy`) are neither listed nor callable. Use this when you only want the agent to observe.
- **`expose_environment`** — `get_site_environment` returns a site's `.env`contents, which include secrets, so it is **disabled by default**. Enable it only when you understand that the secrets are sent to the MCP client/model.
- **`verbose_errors`** — by default a failed Forge call returns a generic message to the client and logs the full exception (via `report()`), so internal details (hostnames, URLs) are not leaked into the model context. Set to `true` in development to return the raw exception message instead.

There are no per-call confirmation prompts at the package level — gate risky operations with `read_only` or by trusting the operator/client.

Usage
-----

[](#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
```

### Read-only mode

[](#read-only-mode)

To let an agent observe but never change Forge state, run the server with [`read_only`](#safety-flags) enabled. MCP clients can pass it as an environment variable on the server command:

```
{
    "mcpServers": {
        "forge": {
            "command": "php",
            "args": ["artisan", "mcp:start", "forge"],
            "env": { "FORGE_MCP_READ_ONLY": "true" }
        }
    }
}
```

With this set, `deploy_site`, `reboot_server`, `update_deployment_script` and `toggle_quick_deploy` are not registered and cannot be called. (This relies on the `read_only` key being wired into `config/services.php` as shown in [Configuration](#configuration).)

Tools
-----

[](#tools)

ToolDescription`list_servers`List all servers in the organization.`get_server`Get a server by ID.`list_sites`List sites on a server.`get_site`Get a site by ID.`get_site_environment`Read a site's environment (.env) file. ⚠️ Exposes secrets; disabled unless `expose_environment` is true.`get_site_nginx_access_log`Nginx access log for a site.`get_site_nginx_error_log`Nginx error log for a site (diagnose 5xx errors).`get_site_application_log`Application log for a site (diagnose app errors).`deploy_site`Trigger a deployment.`get_deployments`Deployment history for a site.`get_deployment`A single deployment, including status.`get_deployment_log`Output log for a deployment (diagnose failures).`get_deployment_script`Get the deployment script.`update_deployment_script`Update the deployment script.`toggle_quick_deploy`Enable/disable quick deploy (push-to-deploy).`reboot_server`Reboot a server.`get_server_log`Server-level log by key (diagnose server issues).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
-------

[](#testing)

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

Contributing
------------

[](#contributing)

See [AGENTS.md](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
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE).

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community8

Small or concentrated contributor base

Maturity49

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 87.5% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

4

Last Release

1d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/9bfb1eae1e3e43813da6740e5eaa39307a95db7561c2d27e7e8aa24233cdcbeb?d=identicon)[andrii-trush](/maintainers/andrii-trush)

---

Top Contributors

[![andrii-trush](https://avatars.githubusercontent.com/u/14265776?v=4)](https://github.com/andrii-trush "andrii-trush (7 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (1 commits)")

---

Tags

laravelmcpaideploymentforge

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/isapp-laravel-forge-mcp/health.svg)

```
[![Health](https://phpackages.com/badges/isapp-laravel-forge-mcp/health.svg)](https://phpackages.com/packages/isapp-laravel-forge-mcp)
```

###  Alternatives

[laravel/boost

Laravel Boost accelerates AI-assisted development by providing the essential context and structure that AI needs to generate high-quality, Laravel-specific code.

3.5k17.6M507](/packages/laravel-boost)[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

76318.2M110](/packages/laravel-mcp)[illuminate/database

The Illuminate Database package.

3.0k54.1M11.0k](/packages/illuminate-database)[moonshine/moonshine

Laravel administration panel

1.3k239.9k72](/packages/moonshine-moonshine)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)