Content
# fleet-mcp
A single MCP server that bundles the tools you use every day to run your hosting
fleet — **SSH/Plesk, WordPress (wp-cli), Cloudflare, MySQL, GitHub, Docker, and
Coolify** — so you can drive all of it from Claude with plain language.
## Tools
| Group | Tools |
|-------|-------|
| **SSH** | `run_ssh` |
| **Sites** | `site_status`, `check_all_sites`, `ssl_expiry`, `disk_usage` |
| **WordPress** | `wp`, `wp_update_plugins`, `wp_purge_lscache`, `wp_health`, `wp_php_handler`, `wp_search_replace`, `wp_integrity`, `wp_core_update`, `wp_maintenance`, `wp_backup` |
| **Cloudflare** | `cf_zone_status`, `cf_dns_list`, `cf_dns_add`, `cf_toggle_proxy`, `cf_export_records`, `cf_zone_restore`, `cf_purge_cache` |
| **MySQL** | `mysql_query`, `mysql_table_sizes`, `mysql_create_user`, `mysql_dump` |
| **GitHub** | `gh`, `gh_pr_list`, `gh_create_issue` |
| **Docker** | `docker_ps`, `docker_logs`, `docker_restart`, `docker_raw` |
| **Coolify** | `coolify_servers`, `coolify_apps`, `coolify_deploy`, `coolify_resources` |
| **OJS** | `ojs_install`, `ojs_create_journal`, `ojs_status` |
| **Dev** | `dev_check`, `scaffold_nextjs`, `scaffold_go`, `scaffold_ts_lib`, `dockerize` |
| **Plesk** | `plesk_list_domains`, `plesk_domain_info`, `plesk_create_subdomain`, `plesk_set_php_handler`, `plesk_create_db`, `plesk_issue_le` |
| **fail2ban** | `f2b_status`, `f2b_check_ip`, `f2b_unban`, `f2b_ignore_add` |
| **Moodle** | `moodle_cron`, `moodle_purge_caches`, `moodle_maintenance`, `moodle_upgrade`, `moodle_cli` |
**Resources:** `fleet://inventory` — a live list of Plesk domains + available PHP
handlers, readable by the model without a tool call.
**Tests / CI:** `npm test` runs the node:test suite (pure functions — creds,
config, result helpers, OJS script builders); GitHub Actions runs build + tests
on every push.
## Setup
```bash
cd fleet-mcp
npm install
cp .env.example .env # then fill in your values
npm run build
```
Requirements on the machine that runs the server:
- **Node ≥ 18** (uses global `fetch`; `--env-file` needs Node ≥ 20.6).
- **ssh** with key auth to the fleet server (recommended over passwords).
- **curl**, **openssl** for the site/SSL tools.
- **gh** CLI for GitHub tools (run `gh auth login` once, or set `GITHUB_TOKEN`).
- **docker** locally, or set `DOCKER_SSH_TARGET` to run it over SSH.
## Register with Claude Code
The easiest way to pass all the credentials is Node's `--env-file`:
```bash
claude mcp add fleet-mcp -- \
node --env-file=/absolute/path/to/fleet-mcp/.env \
/absolute/path/to/fleet-mcp/dist/server.js
```
Then in Claude:
- "Check status of example.com, blog.example.com and shop.example.com"
- "How many days until the SSL cert for journal.example.com expires?"
- "List active plugins on shop.example.com and purge its LiteSpeed cache"
- "Show DNS records for example.org on the secondary Cloudflare account"
- "Back up the myapp_db database"
## Installing an OJS journal
`ojs_install` runs the proven recipe end-to-end and returns the generated admin
+ DB credentials. Two modes:
- **`provision: true`** — full from-scratch: create the Cloudflare A record
(gray), create the Plesk subdomain, deploy files, create DB+user, CLI install,
patch `config.inc.php` (`allowed_hosts`/`base_url`/`trust_x_forwarded_for`),
set perms + PHP handler, issue a Let's Encrypt cert, then flip the record to
proxied. Needs `parentDomain` + `originIp`.
- **`provision: false`** (default) — install into an **existing** webspace
(subdomain, docroot and DNS already set up).
> "Install an OJS journal from scratch on journal.example.com (parent example.com,
> origin 203.0.113.10), create the journal too, English name 'New Journal',
> Arabic 'مجلة جديدة', acronym NJ"
It can optionally create the first journal in the same run (`createJournal`),
applying the three known CLI gotchas (loadAllPlugins throw, missing default
section, per-context theme enable) so the public frontend works immediately.
`ojs_create_journal` does just the journal step on an existing install.
## Dev tools (TypeScript / Go / Next.js)
- `dev_check` — auto-detects the stack and runs vet/build/test (Go) or
install/tsc/lint/build/test (Node/TS).
- `scaffold_nextjs`, `scaffold_go`, `scaffold_ts_lib` — new project skeletons.
- `dockerize` — writes a production multi-stage Dockerfile, ready to build with
`docker_*` and deploy with `coolify_*`.
## Running on a domain for your team (remote mode)
The same tools can run as a shared HTTP server behind a domain:
```bash
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)" # shared team secret
npm run build && npm run start:http # serves POST /mcp on :8787
```
Or via the included [Dockerfile](Dockerfile) — deploy it on your Coolify host,
put it behind `mcp.example.com` (Cloudflare proxied, Full), and have each
teammate add it as a remote MCP server with the bearer token:
```bash
claude mcp add --transport http fleet-mcp https://mcp.example.com/mcp \
--header "Authorization: Bearer <MCP_AUTH_TOKEN>"
```
Security: HTTP mode refuses to start without `MCP_AUTH_TOKEN`. Anyone with the
token can run every tool (including `run_ssh`) — treat it like a root password,
keep the endpoint Cloudflare-proxied, and rotate the token to revoke access.
## Configuration
All config is via environment variables — see [.env.example](.env.example). Nothing
is required at startup; each tool validates its own settings when first called, so
you can enable integrations one at a time.
## Safety notes
- `run_ssh` and `mysql_query` (with `allowWrite=true`) can change server state.
`mysql_query` is **read-only by default** and blocks write/DDL statements unless
you explicitly opt in.
- Secrets live only in `.env` (git-ignored) — never hardcoded. Prefer SSH **key**
auth and scoped **Cloudflare API tokens** (not the global key).
- Some integrations have official MCP servers too (GitHub, Docker). This unified
server trades that for one place to manage your whole fleet; swap individual
groups out later if you prefer the official ones.
## Project layout
```
src/
createServer.ts # builds + registers every tool group (transport-agnostic)
server.ts # local entry point (stdio)
http.ts # remote entry point (Streamable HTTP + bearer auth)
config.ts # env-based config + lazy require* helpers
lib/
exec.ts # safe local + SSH command execution
result.ts # MCP response helpers + error wrapper
creds.ts # crypto-random passwords + label helpers
cloudflare.ts # CF API client
coolify.ts # Coolify API client
ojs-scripts.ts # OJS install + journal-creation script builders
tools/
ssh.ts sites.ts wordpress.ts cloudflare.ts mysql.ts
github.ts docker.ts coolify.ts ojs.ts dev.ts
```
Add a tool by extending the relevant `tools/*.ts` file (or add a new one and call
its `register*` from `server.ts`).
