Server Maintenance MCP Server

A Model Context Protocol (MCP) server designed for Google Antigravity to securely connect, inspect, and maintain remote Linux/Unix servers over SSH.

Features

• 🖥️ Configurable Server Registry: Manage multiple servers with custom IDs, hostnames/IPs, custom ports, usernames, and tags.

• 🔑 Flexible Authentication:

  • OpenSSH private keys (~/.ssh/id_rsa, ~/.ssh/id_ed25519, etc.)

  • Passphrase-protected private keys

  • Password authentication

  • Environment variable interpolation (e.g. "${PROD_PASSWORD}" or "${SSH_KEY_SECRET}")

• 🛡️ Credential Protection:

  • Passwords, passphrases, and private key contents are automatically scrubbed from tool outputs and agent responses.

  • config/servers.json is gitignored by default to prevent accidental credential commits.

• ⚡ Native SSH & SFTP Engine: Powered by ssh2 without relying on host ssh.exe or terminal emulation quirks on Windows.

• 🧰 Agent Toolset:

  • ssh_list_servers: View all configured servers and their metadata.

  • ssh_test_connection: Test connectivity and measure SSH ping/round-trip latency.

  • ssh_execute_command: Run any shell command with working directory, custom timeout, and sudo support.

  • ssh_system_info: Inspect real-time CPU model, cores, load averages, memory usage, disk mounts, and uptime.

  • ssh_read_file: Read remote files with line offsets and line counts over SFTP.

  • ssh_write_file: Upload/edit remote files over SFTP with automatic timestamped backup copies (.bak-...).

  • ssh_list_directory: Explore remote directories over SFTP with file types, sizes, permissions, and timestamps.

  • ssh_service_status: Convenience tool to check, inspect logs, start, stop, or restart systemd services or Docker containers.

Directory Structure

ServerMaintenanceMCP/
├── config/
│   ├── servers.example.json  # Documented configuration template
│   └── servers.json          # Your actual server connections (gitignored)
├── src/
│   ├── config.ts             # Configuration loader & env var expander
│   ├── index.ts              # MCP Stdio Server entrypoint
│   ├── ssh-manager.ts        # SSH & SFTP connection pool and handlers
│   ├── types.ts              # Zod schemas & TypeScript types
│   └── tools/
│       └── index.ts          # Tool schemas and dispatcher
├── test/
│   └── config-and-tools.test.ts # Vitest unit test suite
├── dist/                     # Compiled executable output
├── mcp_config.json           # Antigravity MCP registration template
├── package.json
└── tsconfig.json

Quick Start

1. Configure Your Servers

Copy config/servers.example.json to config/servers.json:

cp config/servers.example.json config/servers.json

Edit config/servers.json with your actual server details:

{
  "defaultKeyPath": "~/.ssh/id_rsa",
  "servers": [
    {
      "id": "prod-web",
      "name": "Production Web & API Server",
      "host": "192.168.1.50",
      "port": 22,
      "username": "ubuntu",
      "privateKeyPath": "~/.ssh/id_rsa",
      "tags": ["production", "web", "docker"],
      "description": "Nginx reverse proxy and API services",
      "defaultCwd": "/var/www"
    },
    {
      "id": "staging-db",
      "name": "Staging Database Server",
      "host": "staging-db.internal",
      "port": 2222,
      "username": "deploy",
      "password": "${STAGING_DB_PASSWORD}",
      "tags": ["staging", "database"],
      "description": "PostgreSQL staging instance"
    }
  ]
}

2. Build the Server

npm run build

To run the automated test suite:

npm test

Antigravity Integration

The server has already been registered in your global Antigravity MCP configuration: ~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "server-maintenance": {
      "command": "node",
      "args": [
        "c:/Users/keesj/Documents/repos/ServerMaintenanceMCP/dist/index.js"
      ],
      "env": {
        "SERVERS_CONFIG_PATH": "c:/Users/keesj/Documents/repos/ServerMaintenanceMCP/config/servers.json"
      }
    }
  }
}

Once registered, restart Antigravity or refresh MCP tools. You can verify available tools under Additional Options (...) > MCP Servers.

Example Antigravity Prompts

Once configured, you can prompt Antigravity directly:

• "List my configured servers and test connection to each one."

• "Check the system health and disk space on prod-web."

• "Inspect the last 50 lines of the Nginx error log on prod-web."

• "Check the status of the docker service on staging-db."

• "Edit /etc/nginx/sites-available/default on prod-web to update the proxy pass URL and test the configuration with nginx -t."