forge-mcp

An MCP server for the Laravel Forge API. It gives Claude 53 tools to read and manage your Forge account, and ships with a skill that teaches the safe order for every job.

Tools	53 — 27 read-only, 26 write, 10 marked destructive
Skill	forge-mcp, installed with the plugin
API	Forge API, verified endpoint by endpoint
Node	18 or newer

---

What it can do

Area	Tools
Account	who the token belongs to, list organizations
Servers	list, get, update, firewall rules, monitors, SSH keys, network, cron
Sites	list, get, create, update, delete, set alias domains
Deployments	history, one deployment, deploy now
SSL	list, request Let's Encrypt, install your own, activate, delete
Site settings	.env, nginx config, run commands, webhooks, heartbeats, redirects, security rules, cron
Organization	recipes, run a recipe, teams, storage providers
Anything else	one tool that reaches any Forge endpoint

---

Install

1. Get a Forge API token

Forge → your name, top right → API → Create token.

Give it only the scopes you want this server to have. It can do nothing beyond what the token allows.

2. Put the token in your environment

export FORGE_API_TOKEN=your_token_here

To keep it across restarts, add that line to ~/.zshrc.

3. Install the plugin

/plugin marketplace add TheBrightLabs/forge-mcp
/plugin install forge-mcp@thebrightlabs

The first command tells Claude where the plugin list is. The second installs the plugin. This is the only method that installs the skill as well as the tools.

4. Restart Claude Code

The server starts when Claude starts.

---

Check it works

Ask Claude:

List my Forge organizations.

You should get your organization back, with its slug. If you do, everything is connected.

---

Install without the plugin

This gives the tools only. The skill does not come with it.

claude mcp add forge --scope user \
  --env FORGE_API_TOKEN=your_token_here \
  -- npx -y @thebrightlabs/forge-mcp

---

Build from source

git clone https://github.com/TheBrightLabs/forge-mcp.git
cd forge-mcp
npm install
npm run build

claude mcp add forge --scope user \
  --env FORGE_API_TOKEN=your_token_here \
  -- node "$(pwd)/dist/index.js"

---

How Forge is organised

Every tool needs the level above it. Start at the top.

ACCOUNT
   │
   ▼
ORGANIZATION            a slug, for example "your-org"
   │                    every other tool needs this
   │
   ├──▶ recipes · teams · storage providers
   │
   ▼
SERVER                  a number, for example 12345
   │
   ├──▶ firewall rules · monitors · SSH keys
   ├──▶ network · scheduled jobs
   │
   ▼
SITE                    a number, for example 67890
       │
       ├──▶ deployments      ├──▶ environment (.env)
       ├──▶ certificates     ├──▶ nginx config
       ├──▶ commands         ├──▶ webhooks
       ├──▶ heartbeats       ├──▶ redirect rules
       ├──▶ security rules   └──▶ scheduled jobs

A site is listed at the organization level, but its parts live under its server. So some tools ask for both a server id and a site id. That is correct, not a mistake.

---

Safety

Guard	What it does
Deleting a site	refuses unless you type that site's exact domain
The raw request tool	refuses any write unless confirm_write is true
Every tool	marked read-only or destructive, so Claude can warn first
The token	read from your environment. Never stored, never logged, never printed

The .env tool returns your application's real secrets. Read it only when you are about to act on it.

---

Environment variables

Name	Required	Purpose
FORGE_API_TOKEN	yes	Your Forge API token

---

Project structure

src/
  index.ts                    starts the server, registers every tool
  forge/
    client.ts                 the one place that talks to Forge
    format.ts                 turns the API response into plain objects
  tools/
    registry.ts               what a tool looks like, shared inputs
    account.ts                who am I, which organizations
    servers.ts                servers, firewall, monitors, SSH keys, network
    sites.ts                  sites, aliases, create, update, delete
    deployments.ts            history, deploy now
    certificates.ts           Let's Encrypt, custom certificates, activate
    siteConfiguration.ts      env, nginx, commands, webhooks, heartbeats,
                              redirects, security rules, cron jobs
    organizationResources.ts  recipes, teams, storage providers
    raw.ts                    reach any endpoint not named above
skills/
  forge-mcp/SKILL.md          the skill installed with the plugin

---

Development

npm install       install dependencies
npm run build     compile TypeScript to dist/
npm start         run the server directly

---

License

MIT