# laravel-forge-mcp

[![npm version](https://img.shields.io/npm/v/@vitrion/laravel-forge-mcp.svg)](https://www.npmjs.com/package/@vitrion/laravel-forge-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)

**Laravel Forge MCP server** — full [Forge API v2](https://forge.laravel.com/docs/api-reference/introduction) coverage for AI assistants via the [Model Context Protocol](https://modelcontextprotocol.io/).

This server uses the **official JSON:API v2 endpoints** (`https://forge.laravel.com/api`). It does **not** use the legacy v1 API (`/api/v1`).

## Features

- **~270 tools** covering servers, sites, deployments, databases, backups, PHP, services, teams, roles, recipes, and more
- Cursor pagination, filtering, sorting, and relationship includes
- Automatic rate-limit retry (429 + `Retry-After`)
- Organization-scoped paths with optional default org via `FORGE_ORGANIZATION`

## Requirements

- Node.js **>= 20**
- A [Forge API token](https://forge.laravel.com/profile/api)

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FORGE_API_TOKEN` | Yes | Bearer token from [Forge API settings](https://forge.laravel.com/profile/api) |
| `FORGE_ORGANIZATION` | No | Default organization slug for org-scoped tools |

`FORGE_API_KEY` is accepted as a silent alias for `FORGE_API_TOKEN`.

## Install

### Cursor

Add to your user config (`~/.cursor/mcp.json`) or project config (`.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "laravel-forge-mcp": {
      "command": "npx",
      "args": ["-y", "@vitrion/laravel-forge-mcp"],
      "env": {
        "FORGE_API_TOKEN": "your-forge-api-token",
        "FORGE_ORGANIZATION": "your-org-slug"
      }
    }
  }
}
```

You can also add the server from **Cursor Settings → Tools & MCP**.

### Claude Desktop

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "laravel-forge-mcp": {
      "command": "npx",
      "args": ["-y", "@vitrion/laravel-forge-mcp"],
      "env": {
        "FORGE_API_TOKEN": "your-forge-api-token",
        "FORGE_ORGANIZATION": "your-org-slug"
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add laravel-forge-mcp -- npx -y @vitrion/laravel-forge-mcp
```

Set `FORGE_API_TOKEN` (and optionally `FORGE_ORGANIZATION`) in your shell environment or MCP host config.

## Tool groups

Tools are named in kebab-case and map one-to-one to Forge API v2 operations:

| Group | Examples |
|-------|----------|
| **User & organizations** | Current user, org list, server credentials, VPCs |
| **Servers** | CRUD, actions (reboot), archives, network, events |
| **Sites** | Global/org/server sites, env, nginx, health, load balancing, composer/npm credentials |
| **Domains & certificates** | Domains, DNS, nginx, certificates, domain actions |
| **Deployments** | Deployments, scripts, push-to-deploy, deploy hook/key, webhooks |
| **Background processes** | CRUD, logs, start/stop/restart actions |
| **Databases & backups** | Schemas, users, backup configs/instances, restores |
| **Storage providers** | S3-compatible backup storage CRUD |
| **Scheduled jobs & commands** | Server/site cron jobs, site commands |
| **Firewall, SSH & monitors** | Firewall rules, SSH keys, uptime monitors, server logs |
| **Nginx, security & redirects** | Templates, security rules, redirect rules |
| **Integrations & logs** | Horizon, Octane, Reverb, Pulse, site logs, heartbeats |
| **Recipes** | Org recipes, forge recipes, team shares |
| **Teams & roles** | Teams, members, invites, shares, roles, permissions |
| **Providers** | Cloud providers, sizes, regions |
| **PHP & services** | PHP versions/configs/OPcache, service actions (nginx, mysql, redis, …) |

List tools support shared query parameters: `include`, `filter`, `sort`, `pageSize`, and `cursor`.

## Development

```bash
git clone https://github.com/vitrionbv/laravel-forge-mcp.git
cd laravel-forge-mcp
npm install
npm run build
npm test
npm run dev
```

## Inspector

Debug the MCP server with the official inspector (requires a built `dist/`):

```bash
npm run build
npm run inspector
```

Or directly:

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

## License

MIT — see [LICENSE](LICENSE).

## Repository

[vitrionbv/laravel-forge-mcp](https://github.com/vitrionbv/laravel-forge-mcp)