Skip to main content
Glama

ServerAvatar MCP

tests lint audit docker License: MIT

ServerAvatar MCP is an independent open-source project. It is not affiliated with, endorsed by or sponsored by ServerAvatar.

A self-hosted, multi-user web app that exposes a curated set of ServerAvatar actions to AI clients over MCP, so a team can use its servers without sharing ServerAvatar credentials.

Status: release candidate 1.0.0-rc.1. Accounts, OAuth, the MCP endpoint, the activity log and dashboard, the encrypted ServerAvatar token vault, the 16 read-only tools and the 8 tools that change things (restart, supervisors, applications, domains, SSL, databases, database user access, cron jobs) are built and tested. Seven of the eight (restart, create database, create application, add a domain, install SSL, change database user access, create a cron job) were also run on a test server. Of the 14 application types, five were created live (plain PHP, WordPress, phpMyAdmin, Joomla, Statamic); the other nine follow ServerAvatar's documentation and have not been run. The eighth write tool, control_supervisor, also follows the documentation only. A security review, a dependency audit and a load test are done (see SECURITY.md). The Docker setup was run by hand and is built and smoke-tested by CI on every push.

See the changelog, the design notes, what the live ServerAvatar API does and the tools.

How it works

  • No sign-up. People can only log in. Admins are created only from the terminal; the dashboard creates normal users, never admins.

  • A user created by an admin, or whose password an admin resets, must choose a new password before doing anything else.

  • An AI client (claude.ai, Claude Code, Cursor) connects to https://your-host/mcp using OAuth 2.1: it registers itself, the user signs in here and chooses a permission level (read, read + safe actions, or full), and the client receives short-lived tokens. Tools above that level are not listed and are refused if called.

  • Each user saves one ServerAvatar API token on the ServerAvatar token page. It is checked with ServerAvatar before it is saved, stored encrypted, and never shown again (only its last four characters). A user without a token is sent to that page before they can connect an AI client. Deleting the token disconnects their AI clients.

  • Users see and manage their own connections on Connections: change the level (it applies at once) or revoke.

  • Every sign-in, admin action and MCP request is written to the activity log (kept 90 days): who, which client, which tool, the result and the time taken, with secrets removed from the arguments.

  • When an admin resets a user's password, disables them or deletes them, that user's AI clients are disconnected at once.

Related MCP server: ConnectPX MCP OAuth Demo

Development setup

Requires PHP 8.2+ (with sodium and pdo_mysql), Composer, Node 22+ and MySQL or MariaDB.

composer install
npm ci
cp .env.example .env
php artisan key:generate
php artisan passport:keys          # signing keys for access tokens (never committed)

# Database: create it once, then migrate. (.env uses 127.0.0.1:3306, user root, no password.)
mysql -uroot -e "CREATE DATABASE serveravatar_mcp CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
php artisan migrate

# The first admin (password from a hidden prompt, or the ADMIN_PASSWORD variable; never an argument)
php artisan serveravatar:create-admin you@example.com --name="Your Name"

npm run build     # or `npm run dev` while working on the UI
php artisan serve

Then open http://localhost:8000 and sign in. The admin creates users from Admin → Users. Run php artisan schedule:work (or a cron entry for schedule:run) so the daily clean-ups run.

serveravatar:create-admin refuses an email that already exists, so an existing account can never be turned into an admin.

Connecting an AI client

Step-by-step guides for claude.ai, Claude Code and Cursor, and what to do when something goes wrong, are in docs/setup.md. To run the app for a team, see docs/self-hosting.md. In short:

On the Connections page the app shows its MCP address (…/mcp). In claude.ai: Settings → Connectors → Add custom connector, paste the address. In Claude Code: claude mcp add --transport http serveravatar <address>, then /mcp to sign in. The client opens this app's sign-in and consent pages; after approval, ask Claude something like “list my servers” to check the connection. If you connected before the tools were added, remove and re-add the connector so the client reloads the tool list.

claude.ai calls your server from the internet, so it needs a public HTTPS address. To try it from a laptop with a tunnel (for example Cloudflare Tunnel or ngrok):

  1. Start the tunnel to http://127.0.0.1:8000 and note its https://… address.

  2. In .env set APP_URL=https://that-address (the app answers only to this host, so every time the tunnel gets a new address, update it and run php artisan config:clear, or you will see 400 Invalid host), TRUSTED_PROXIES=127.0.0.1 (the tunnel program reaches the app from the same machine) and APP_DEBUG=false. A tunnel is public, and debug mode would show stack traces and request data to anyone. Then run php artisan config:clear.

  3. Open https://that-address/.well-known/oauth-authorization-server and check that every URL in it starts with exactly https://that-address/. A URL starting with http:// means TRUSTED_PROXIES is not set correctly; a different host means the tunnel rewrites the Host header.

  4. Add https://that-address/mcp as a custom connector in claude.ai and approve it.

Settings in .env (see .env.example): SERVERAVATAR_API_URL (the API address), SERVERAVATAR_TIMEOUT, SERVERAVATAR_SLOW_TIMEOUT (for creating applications) and SERVERAVATAR_MAX_RETRIES for calls to ServerAvatar, MCP_REDIRECT_DOMAINS limits where a client may be sent after approval (never *), OAUTH_ACCESS_TOKEN_MINUTES and OAUTH_REFRESH_TOKEN_DAYS set token lifetimes, MCP_RATE_LIMIT and OAUTH_REGISTER_RATE_LIMIT set request limits.

Tests and checks

Tests run on their own database, because they wipe it:

mysql -uroot -e "CREATE DATABASE serveravatar_mcp_test CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci"
vendor/bin/pest          # backend tests (Vite is faked, no build needed; signing keys are created if missing; no test can reach the real ServerAvatar API)

# Optional, read-only checks against the real ServerAvatar API (skipped unless a token is given):
SERVERAVATAR_TOKEN=your-token vendor/bin/pest tests/Integration
vendor/bin/pint --test   # PHP style
npm run format:check && npx eslint . && npx tsc --noEmit

Password rules: at least 12 characters with upper and lower case letters and a number (plus a breach check in production). Passwords are hashed with argon2id.

Behind a reverse proxy

Set TRUSTED_PROXIES (comma-separated IPs or CIDR ranges, or * only if the app is reachable solely through your own proxy). By default no proxy is trusted, so a forged X-Forwarded-For cannot change the IP recorded in the activity log. Whatever you trust, the app only answers to the host in APP_URL (plus TRUSTED_HOSTS, if set, and localhost), so a forged X-Forwarded-Host cannot redirect OAuth addresses or password-reset links to another domain.

To run it in containers, see the Docker Compose section of docs/self-hosting.md.

Contributing, security and licence

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI tools to perform server operations such as log inspection, system monitoring, code management, Nginx and certificate management, with support for local and remote SSH modes and built-in security controls.
      23
      72 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Lets AI assistants such as Claude, ChatGPT, or Cursor connect to a Pterodactyl panel over OAuth 2.1 and act as the signed-in user to read consoles, edit files and configs, send commands, restart servers, and manage schedules. Every tool call is limited to the scopes the user approves and the panel permissions their account already holds, with all actions recorded in the activity log.
      3
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI clients to connect to a user's Karlancer account through OAuth-scoped, human-approved tools for discovering projects, preparing and submitting proposals, and managing conversations on self-hosted infrastructure.
      MIT