AgenSysAdmin

AgenSysAdmin

MCP server for AI-assisted Linux administration over SSH. Works with OpenAI/Codex, Anthropic, and other MCP-compatible clients to inspect and manage Ubuntu/Debian servers.

The server exposes 21 tools for monitoring, security audits, Docker, service management, backups, package updates, and controlled command execution.

Setup

python -m venv .venv
.venv/Scripts/activate   # Windows
# source .venv/bin/activate  # Linux/Mac
pip install -e ".[dev]"

Configuration

1. Copy servers.yaml.example to servers.yaml and edit with your server details.
2. Copy .env.example to .env and set SSH key paths or passwords.

MCP Integration

Run the server with:

python -m agensysadmin

Use that command in any client that supports local MCP servers. Example configuration:

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "sysadmin": {
      "command": "python",
      "args": ["-m", "agensysadmin"],
      "cwd": "D:/AI/AgenSysAdmin"
    }
  }
}

Available Tools

| Tool | Description | |------|-------------| | list_servers | List configured servers and connection status | | system_info | OS, uptime, CPU, RAM, load average | | disk_usage | Disk and filesystem usage | | check_services | Systemd service status | | check_ports | Listening TCP ports | | process_list | Top processes by CPU/memory | | execute_command | Run any shell command | | install_package | Install packages through the detected package manager | | manage_service | Start, stop, restart, enable, or disable systemd services | | edit_config | Read or update a remote configuration file with optional backup | | docker_ps / docker_logs / docker_images | Inspect Docker state | | docker_compose | Run controlled Docker Compose actions | | check_updates | Inspect available system and security updates | | firewall_status | Inspect firewall configuration | | security_audit | Run a focused server security audit | | full_security_audit | Run the complete multi-category security audit | | create_backup / list_backups | Create and inspect server backups | | check_cron | Inspect scheduled jobs | | generate_report | Generate a consolidated server report |

Safety

• Keep servers.yaml, .env, SSH keys, passwords, and production addresses out of version control.
• Prefer read-only inspection tools before mutation tools.
• Require explicit confirmation in your AI client before package installation, service changes, configuration edits, backups, Docker Compose actions, or arbitrary commands.
• Use a dedicated SSH account with the minimum permissions required for each server.

Tests

pytest tests/ -v