server-admin-mcp

An MCP server that administers a Debian 13 stage host over SSH: monitoring, Docker Compose, deployment, PostgreSQL, logs, Nginx/TLS, firewall and scheduled automation — 82 tools and 4 workflow prompts.

Stage environments only. This server gives an assistant broad, real access to a machine. Everything destructive sits behind an explicit confirmation step, and a denylist rejects unrecoverable commands outright, but neither is a substitute for pointing it at a host you can afford to rebuild. See Security warnings.

Contents

• Installation

• Configuration

• Preparing the server

• Connecting a client

• Safety model

• Tool reference

• Prompts

• Testing

• Security warnings

• Troubleshooting

• Design decisions

Installation

Requires Node.js 20 or newer on the machine running the MCP client (not on the server).

npm install
npm run build

This produces dist/index.js, which is the entry point your MCP client launches. The server speaks MCP over stdio; it never opens a port of its own.

Available scripts:

Configuration

Every setting is an environment variable prefixed SRVMCP_. Copy .env.example and fill it in, then pass the values through your client's env block.

Optionally, a JSON file with the same keys in camelCase can be pointed at with SRVMCP_CONFIG_FILE (default ./config.json when it exists). Environment variables always win over the file.

SSH connection

Project layout on the server

PostgreSQL

Reached by running psql on the server, so SRVMCP_PG_HOST is resolved from the server's point of view (localhost or 127.0.0.1 for a container publishing 5432).

Limits and behaviour

Configuration is validated at startup with zod. A missing or wrong value produces a message naming the variable and how to fix it, and the process exits before the transport opens — so the client shows the error instead of hanging.

Preparing the server

The server should connect as a dedicated, restricted user — not root.

1. Create the deploy user

sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /home/deploy/.ssh
sudo chmod 700 /home/deploy/.ssh

Add the MCP server's public key:

echo 'ssh-ed25519 AAAA... server-admin-mcp' | sudo tee -a /home/deploy/.ssh/authorized_keys
sudo chmod 600 /home/deploy/.ssh/authorized_keys
sudo chown -R deploy:deploy /home/deploy/.ssh

2. Grant Docker access

sudo usermod -aG docker deploy

Group membership only applies to new sessions — restart the MCP server afterwards so it reconnects.

3. Give the project directory to deploy

sudo chown -R deploy:deploy /opt/stage

4. A narrow sudoers file

Only the binaries the tools actually need, with no password prompt (an interactive prompt would hang a non-interactive session):

sudo visudo -f /etc/sudoers.d/deploy-mcp

deploy ALL=(root) NOPASSWD: /usr/bin/systemctl, /usr/sbin/nginx, /usr/bin/journalctl, \
    /usr/bin/apt-get, /usr/sbin/ufw, /usr/bin/certbot, /usr/bin/install, \
    /usr/bin/crontab, /usr/sbin/logrotate, /usr/bin/systemd-analyze, \
    /usr/bin/fail2ban-client, /bin/ln, /bin/rm, /bin/cat, /usr/bin/openssl

sudo chmod 440 /etc/sudoers.d/deploy-mcp
sudo visudo -c        # verify before logging out

Grant only what you need. Dropping /usr/bin/apt-get disables package upgrades; dropping /usr/sbin/ufw disables firewall changes. Each affected tool then returns an actionable "this needs a sudoers entry" error rather than failing obscurely.

To read logs without sudo, add the user to adm instead:

sudo usermod -aG adm deploy    # /var/log/nginx, journal

5. Create a read-only PostgreSQL role

CREATE ROLE mcp_ro LOGIN PASSWORD 'choose-a-strong-password';
GRANT CONNECT ON DATABASE stage_db TO mcp_ro;
GRANT USAGE ON SCHEMA public TO mcp_ro;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO mcp_ro;
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO mcp_ro;

The ALTER DEFAULT PRIVILEGES line matters: without it, tables created by future migrations are invisible to mcp_ro. It applies to objects created by the role that runs it, so run it as the role owning your migrations. pg_fix_schema_permissions applies this whole set for you.

Optionally, a separate write role for pg_write, pg_maintenance, pg_restore_db and pg_fix_schema_permissions:

CREATE ROLE mcp_rw LOGIN PASSWORD 'another-strong-password';
GRANT CONNECT ON DATABASE stage_db TO mcp_rw;
GRANT USAGE, CREATE ON SCHEMA public TO mcp_rw;
GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO mcp_rw;
ALTER DEFAULT PRIVILEGES IN SCHEMA public
    GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO mcp_rw;

Leaving SRVMCP_PG_WRITE_USER unset makes every database write structurally impossible, which is a good default until you need one.

psql must be installed on the server: sudo apt-get install -y postgresql-client.

6. Record the host key

ssh-keyscan -p 22 stage.example.com >> ~/.ssh/known_hosts

Verify the fingerprint out of band before trusting it, then point SRVMCP_KNOWN_HOSTS_PATH at that file.

Connecting a client

Claude Desktop / Claude Code

claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "server-admin": {
      "command": "node",
      "args": ["/absolute/path/to/server-admin-mcp/dist/index.js"],
      "env": {
        "SRVMCP_HOST": "stage.example.com",
        "SRVMCP_USER": "deploy",
        "SRVMCP_PRIVATE_KEY_PATH": "/home/you/.ssh/id_ed25519",
        "SRVMCP_KNOWN_HOSTS_PATH": "/home/you/.ssh/known_hosts",
        "SRVMCP_PROJECT_ROOT": "/opt/stage",
        "SRVMCP_ALLOWED_PATHS": "/opt/stage,/etc/nginx,/var/log",
        "SRVMCP_PG_HOST": "localhost",
        "SRVMCP_PG_USER": "mcp_ro",
        "SRVMCP_PG_PASSWORD": "...",
        "SRVMCP_PG_DATABASE": "stage_db",
        "SRVMCP_AUDIT_LOG_PATH": "/var/log/server-admin-mcp/audit.log"
      }
    }
  }
}

Use absolute paths — the client's working directory is not yours.

A read-only instance, useful for giving an assistant visibility without any ability to change anything:

{
  "mcpServers": {
    "stage-readonly": {
      "command": "node",
      "args": ["/absolute/path/to/server-admin-mcp/dist/index.js"],
      "env": { "SRVMCP_READ_ONLY": "true", "SRVMCP_HOST": "...", "SRVMCP_USER": "deploy" }
    }
  }
}

Safety model

Four independent layers, applied in this order:

1. Denylist — absolute, cannot be overridden

Checked on the fully assembled command string inside the SSH layer, so no tool can route around it, and confirm: true does not help. It targets commands that are unrecoverable on a remote box with no console:

The error names the rule that fired, so it is obvious what triggered and why.

Beyond the denylist there is one more hard guard: sec_firewall_rule refuses to deny or delete the SSH port, because applying that rule would disconnect the server permanently.

2. Confirmation — preview, then execute

Destructive tools take confirm: boolean. Without confirm: true the tool executes nothing and instead returns a preview: the exact command, the resulting state change, what is irreversible, and what to check first.

PREVIEW — nothing has been executed.

Command that would run:
  $ docker volume prune -f

Effect: Deletes every Docker volume not currently attached to a container.
Irreversible: YES — volume data cannot be recovered. A stopped database
container makes its data volume look unused.

Before approving:
  - Run compose_ps first: every stack service must exist, otherwise its
    volume counts as unused.
  - Take a database backup with pg_backup and copy it off the server first.

To execute, call docker_prune again with the same arguments plus confirm: true.

Tools requiring confirmation: sys_service_control (stop only), sys_run_command (when the command mutates state), docker_exec (same), compose_action (down/stop/rm), docker_prune, docker_volume_remove, git_reset, deploy_run, migration_run, pg_write, pg_kill_query, pg_maintenance, pg_restore_db, pg_fix_schema_permissions, nginx_write_config, nginx_enable_site, nginx_disable_site, ssl_renew, sec_firewall_rule, sec_package_upgrade, env_set, all five auto_* tools, and file_write/file_patch outside PROJECT_ROOT.

For free-form commands (sys_run_command, docker_exec) confirmation is demanded when the command contains rm, mv, truncate, kill/pkill, chmod/chown, apt, an overwriting redirect (>, but not 2>&1), a Docker removal, or destructive SQL.

3. Path allowlist — checked twice

Every file operation normalises the path (resolving ..), then verifies it is inside one of SRVMCP_ALLOWED_PATHS. A second check runs on the server after readlink -f, so a symlink planted inside an allowed root cannot be used to reach outside it. A sibling with a shared prefix (/opt/stagemore against /opt/stage) is correctly excluded.

4. Audit log — every call, JSONL

Every invocation is appended to SRVMCP_AUDIT_LOG_PATH, successful or not:

{"ts":"2026-07-25T10:00:00.000Z","tool":"compose_action","args":{"action":"restart","services":["api"],"confirm":true},"status":"ok","command":"docker compose -f /opt/stage/docker-compose.yml restart api","exitCode":0,"durationMs":1234,"confirmed":true}

Writes are queued so concurrent calls cannot interleave, and a failure to write warns on stderr without aborting the tool. Credentials are masked before anything is written.

Read-only mode

With SRVMCP_READ_ONLY=true, tools whose readOnlyHint is false are never registered — 49 tools are exposed instead of 82, and a write tool is not merely refused but absent from tools/list entirely. There is no runtime flag an assistant could flip.

Secret masking

Everything leaving the process — tool text, structured content and audit records — passes through a masker covering password/secret/token/api_key/auth/credential-style keys, Bearer/Basic headers, credentials embedded in URLs, JWTs, PEM private-key blocks and PGPASSWORD=. docker_inspect masks environment values by key name, and env_read masks every value unless a single revealKey is named explicitly.

Database credentials are never placed on a command line: a ~/.srvmcp.pgpass file (mode 0600) is written once and referenced through PGPASSFILE, keeping the password out of ps output entirely.

Tool reference

82 tools. RO marks read-only (available in read-only mode); ! marks tools requiring confirm.

System — sys_* (10)

Docker — docker_*, compose_* (13)

Deployment and git — git_*, deploy_*, migration_* (9)

PostgreSQL — pg_* (13)

Logs — log_* (6)

Nginx and TLS — nginx_*, ssl_* (9)

Security — sec_* (9)

Files — file_*, env_* (8)

Automation — auto_* (5)

Prompts

Testing

Unit tests — no server required

npm test

134 assertions covering the denylist (each dangerous command individually, plus a set of safe ones that must not be blocked), the path allowlist including traversal and shared-prefix cases, middle-out truncation, control-character sanitising, secret masking, shell quoting, read-only SQL classification (including SELECT 1; DROP TABLE users), and CSV parsing.

Schema inspection

npm run inspect

Confirms all 82 tools list with valid input and output schemas and complete annotations.

Smoke test — read-only, against the real server

npm run smoke              # every read-only tool
npm run smoke -- sys_ pg_  # only these prefixes

Calls each read-only tool in turn and prints a pass/fail table. It never invokes a tool whose readOnlyHint is false, so it is safe against a live stage box.

Security warnings

This server grants an assistant broad, real access to a machine. Treat it accordingly.

• Stage only. Do not point it at production. Nothing here distinguishes the two for you.

• Never connect as root. Use a dedicated user with the narrow sudoers file above. The safety layers are defence in depth, not a replacement for least privilege.

• Prefer read-only. SRVMCP_READ_ONLY=true removes 33 write tools from the interface entirely. Run a second, writable instance only when you need it.

• Leave SRVMCP_PG_WRITE_USER unset until a database write is genuinely required — that makes pg_write, pg_restore_db and pg_maintenance structurally unavailable.

• Set SRVMCP_KNOWN_HOSTS_PATH. Without it the first connection is trusted blindly, which makes a man-in-the-middle attack possible on the first connect.

• Review the audit log. It records every call with arguments and exit codes. It is the only record of what was actually done:

  tail -f audit.log | jq 'select(.confirmed == true)'          # everything executed with confirmation
  jq 'select(.status == "error")' audit.log                     # everything that failed
  jq -r '[.ts, .tool, .command] | @tsv' audit.log               # a readable timeline

• Keep SRVMCP_ALLOWED_PATHS tight. Every added root widens what can be read and written. Adding / defeats the mechanism.

• The private key is the whole boundary. Anyone who can read it, and the environment holding the passphrase, has the same access this server does.

• Backups made by pg_backup and auto_setup_backup stay on the same host as the database. They protect against a bad migration, not against losing the server. Arrange an off-box copy separately.

Troubleshooting

SSH authentication to deploy@host:22 failed (permission denied)

The key is wrong or not authorised. Reproduce outside the MCP server:

ssh -i ~/.ssh/id_ed25519 -p 22 deploy@stage.example.com

Check the public half is in /home/deploy/.ssh/authorized_keys, and that modes are 700 on ~/.ssh and 600 on authorized_keys — sshd silently refuses looser permissions.

Host key verification failed

Either the host is not in known_hosts yet, or its key changed. Verify the fingerprint out of band, then:

ssh-keyscan -p 22 stage.example.com >> ~/.ssh/known_hosts

A changed key on a host you have connected to before deserves investigation before you clear the old entry.

Cannot talk to the Docker daemon: permission denied on /var/run/docker.sock

sudo usermod -aG docker deploy

Then restart the MCP server — group membership only applies to new sessions.

The command needs sudo but the account cannot use it without a password

The binary is missing from /etc/sudoers.d/deploy-mcp. Add it, then sudo visudo -c to verify. A prompting sudo hangs a non-interactive session, which is why sudo -n is used throughout.

The command timed out after 60s

Either raise timeoutMs for that call, or start the work in the background:

sys_run_background(command: "...")   ->  sys_check_background(pid: 1234)

Builds, migrations, large upgrades and pg_dump on a big database are the usual candidates. deploy_run already allows 30 minutes for the build step.

Cannot reach PostgreSQL at localhost:5432

SRVMCP_PG_HOST is resolved from the server's point of view. If the database runs in Docker, check docker_ps for the published port — usually 127.0.0.1:5432. If it is not published at all, run queries inside the container with docker_exec instead.

Refused: path "/etc/shadow" is outside the configured allowlist

Working as intended. Add the root to SRVMCP_ALLOWED_PATHS only if you genuinely want it reachable.

permission denied for schema public after upgrading to PostgreSQL 15

PostgreSQL 15 removed the implicit CREATE grant on public from PUBLIC. Fix it in one call:

pg_fix_schema_permissions(user: "app_user", schema: "public", confirm: true)

A tool is missing from tools/list

Check whether SRVMCP_READ_ONLY=true — write tools are not registered in that mode. The server logs N tools registered, M withheld (read-only mode) to stderr at startup.

Nginx logs are unreadable

They are root-owned by default:

sudo usermod -aG adm deploy

The audit log is not being written

The server warns once on stderr and keeps working. Check that the directory exists and is writable by whoever runs the MCP client.

Design decisions

Choices made where the specification left room, recorded here as required.

Project at the repository root, not in a server-admin-mcp/ sub-directory. The working directory was already the project root; nesting would have added a level for no benefit. The package is still named server-admin-mcp.

Two extra source files beyond the specified layout. src/utils/shell.ts holds shell quoting, and src/safety/paths.ts holds the path allowlist — both are separate concerns that would otherwise have been duplicated across nine tool modules. src/tools/registry.ts, src/tools/types.ts and src/tools/context.ts hold the shared registration, envelope and dependency plumbing that keeps each tool module free of boilerplate. src/ssh/knownHosts.ts implements host-key verification, which ssh2 leaves to the caller.

Manual POSIX quoting instead of shell-quote. Single-quoting is five lines; for a server with this much reach, one fewer dependency to audit was worth more than the package.

PGPASSFILE instead of PGPASSWORD. The specification asked for the password to be passed by environment rather than visibly in the command. Because the environment is exported inside the remote sh -c string, PGPASSWORD would still appear in ps output. A ~/.srvmcp.pgpass file at mode 0600, referenced through PGPASSFILE, keeps it out of process listings entirely.

Uniform output envelope. Every tool's outputSchema carries status and message alongside its own fields, with tool-specific fields optional. That is what lets a confirm preview validate against the same schema as a successful run, so previews are ordinary results rather than errors.

Statement batching rejected in pg_query. Checking only the first keyword would let SELECT 1; DROP TABLE users through. String literals and comments are stripped before keyword matching so a value like 'delete from users' is not mistaken for a write.

Remote timeout(1) plus a local timer. Killing the SSH channel alone leaves the remote process running. The command is wrapped in timeout -k 5s, so it dies on the server; the local timer is only a backstop for a wedged channel.

Atomic writes and double path checking. Files are written to a temporary sibling and renamed, so an interrupted transfer cannot leave a half-written config. Paths are checked textually and again on the server after readlink -f, so a symlink inside an allowed root cannot escape it.

ssl_renew defaults to dryRun: true. Let's Encrypt rate-limits real issuance; a dry run costs nothing and catches a broken challenge setup.

sec_firewall_rule will not touch the SSH port. Not a confirmation — a refusal. Applying such a rule would disconnect the server with no way back in, so it must be done from a console session.

auto_setup_backup test-runs the script before scheduling it. A backup that only fails at 3 a.m. is worse than no backup, so nothing is added to cron until one real dump has succeeded.

Extra tools beyond the specification. file_stat (metadata for a single path, useful when diagnosing permissions) and migration_status support for Alembic alongside EF Core and Django.

docker_exec requires confirmation for mutating commands, matching the rule the specification set for sys_run_command; it is the same class of escape hatch.