Skip to main content
Glama
AgenSysAdmin

AgenSysAdmin

by E13ctr0N

AgenSysAdmin

MCP server for AI-assisted administration of Debian/Ubuntu hosts over SSH. The consolidated codebase keeps the local project's useful sessions, sudo support, role metadata, journal and extended audits while enforcing diagnostic-only defaults.

27 MCP tools · 12 audit categories · operator-owned permissions · metadata-only history

Install

python -m venv .venv
# Activate .venv for your platform, then:
python -m pip install -e ".[dev]"

Python 3.11+ is required. The MCP SDK stays on its compatible 1.x API. The agensysadmin console command is equivalent to python -m agensysadmin.

Related MCP server: vps-mcp

Keep operational data private

Create a workspace outside this Git checkout using the anonymized template. Copy example configuration there as servers.yaml and .env. Protect the directory with operator-only permissions or Windows ACLs.

python -m agensysadmin --config-dir /absolute/private/workspace config validate
python -m agensysadmin --config-dir /absolute/private/workspace

Use an absolute Python executable as the MCP client's stdio command, with args equivalent to:

["-m", "agensysadmin", "--config-dir", "/absolute/private/workspace"]

This works independently of the launcher's working directory. AGENSYSADMIN_CONFIG_DIR is an alternative; without either setting, configuration comes from the current directory. Direct agensysadmin.server:mcp launchers should set the environment variable before import. Client-specific configuration wrappers differ.

Never publish real inventories, .env, SSH keys, logs, server notes, browser captures or downloaded executables. Publication checks run in CI as an additional safeguard, not a comprehensive secret detector.

Trust, credentials and permissions

servers:
  staging:
    host: staging.example.invalid
    user: operator
    key_env: STAGING_SSH_KEY_PATH
    role: Example container host
    profile: docker_host
    known_hosts_path: ~/.ssh/known_hosts
    allow_mutations: false
    allow_arbitrary_commands: false
    config_read_paths: []
    config_write_paths: []
    # sudo_password_env: STAGING_SUDO_PASSWORD

Choose a verified host_key_sha256 OR known_hosts_path. Verify the fingerprint through an independent trusted channel; unverified key discovery is not identity verification. Fingerprint pins are enforced before authentication. Explicit trust files are exclusive, and missing files fail. known_hosts_file is accepted as a safe legacy spelling; automatic trust is not supported. For a non-default SSH port use the OpenSSH [host]:port known-host entry format.

Credentials are resolved from named environment variables, with process environment taking precedence over the workspace .env. Loading does not mutate process environment or expand ${...} inside passwords. Missing explicit references fail. SSH-agent and automatic-key discovery are opt-in via allow_agent and look_for_keys.

Capability

Required operator settings

Structured diagnostics, service status, Compose ps/logs

Available by default; actual SSH/sudo permissions still apply

Privileged config-file read

Exact path in config_read_paths

Package/service changes and backup creation

allow_mutations: true

Direct shell commands and Compose mutations

Both permission flags

Config replacement

Both flags and exact path in config_write_paths

File allowlists accept exact absolute POSIX file paths, without traversal or globs. Reads/writes reject direct symlinks and special files. Remote parent directories must be trusted. Restart the MCP process after changing local policy. Client per-action confirmation is still required for remote changes; a configuration grant is not human approval of every invocation.

These controls govern the MCP interface, not arbitrary Python callers or a privileged-account sandbox. Managed package/service administration is powerful. Restrict remote accounts and sudo permissions; do not grant broad sudo just to make every audit pass. Remote output can contain secrets or malicious instructions and must be treated as untrusted data.

Enrollment and sessions

Enrolling hosts and changing trust are local operator operations, never model-supplied MCP arguments:

python -m agensysadmin --config-dir /absolute/private/workspace config add-server --name staging --host staging.example.invalid --user operator --key-env STAGING_SSH_KEY_PATH --profile docker_host --known-hosts-file /absolute/private/known_hosts

Enrollment is offline and stores credential variable names only. --replace explicitly replaces an alias's complete configuration; re-specify required permissions and allowlists. --read-config-path/--write-config-path add exact file capabilities. CLI edits reserialize YAML; keep operational notes separately. config validate --without-secrets checks schema/references without resolving credentials.

start_session connects a configured alias; sessions use keepalive and expose connection time and per-session command counts. end_session closes it. connect_server and disconnect_server are compatibility aliases for those operations. connect_server no longer accepts raw hosts, passwords, trust overrides or save=True.

Root executes privileged operations directly, without requiring sudo installed. Non-root uses noninteractive sudo or an operator-configured sudo_password_env. Password and config stdin are separated by a framing marker so cached/NOPASSWD sudo cannot prepend a password to file content. Passwords never enter command arguments or the journal. Live sudo/PAM/TTY policies require staging verification.

Tools and audits

Area

Tools

Sessions/history

list_servers, start_session, end_session, connect_server, disconnect_server, operation_journal

Monitoring

system_info, disk_usage, check_services, check_ports, process_list

Administration

execute_command, install_package, manage_service, edit_config

Docker

docker_ps, docker_logs, docker_images, docker_compose

Security

security_audit, full_security_audit, check_updates, firewall_status

Backups/reports

create_backup, list_backups, check_cron, generate_report

Full audit categories: SSH, firewall, users/auth, network, filesystem, services, updates, logs, kernel, malware, VPN/tunnels and Docker security. Profiles are generic, vpn_node, docker_host, web, and database; role/description are display metadata. Expected VPN software and forwarding are contextual rather than automatically insecure.

Docker inspection collects selected fields, excluding environment secrets, with bounded explicit coverage. VPN inventory covers TCP/UDP, IPv4/IPv6 and JSON interface kinds with custom names. Listener presence does not prove external reachability, TLS safety or authorization. TLS/Trivy/Lynis availability is inventory, not a completed vulnerability scan.

Findings distinguish PASS, WARN/FAIL, UNKNOWN and NOT_APPLICABLE. INFO/N_A do not improve scores. Incomplete categories are explicit; a category with no scored checks has score=null. Identical facts are reused within one full audit. Scores are heuristics, not security certification. Update inspection uses the existing apt cache without refreshing it. SSH settings use sshd -T -C with the SSH account/address gathered before elevation; DNS-hostname Match rules, other accounts and daemon startup overrides still need separate checks. Full audits require Bash/GNU/Linux tools and suitable permissions.

Writes, backups and history

Commands have deadlines and a 2 MiB combined output bound. A timeout/output error closes the channel but does not prove remote termination or rollback: verify state before retrying. Config writes are bounded to 256 KiB and travel through SSH stdin. The writer verifies byte count, preserves available existing attributes and atomically replaces the file.

Config backups use unique private files and return backup_path plus backup_metadata_path. The sidecar records restoration metadata; ACL/xattr collection is best-effort when platform tools are available. Restore is a separately approved operation. Archives use private temporary files and publish only on success; existing archive names and destinations inside the source tree are rejected. Backup operands must be absolute. list_backups.size is a byte-count string. Docker logs default to 100 lines (maximum 10,000).

The journal stores operation types, aliases, timestamps, command hashes, result codes, durations and byte counts only. It never stores command text, stdout/stderr or credentials. Files rotate by size; reads are bounded to the current file and at most 500 entries. POSIX files use mode 0600; Windows uses inherited workspace ACLs. This is per-process troubleshooting history, not tamper-proof multi-process auditing. If a completed command returns journal_warning=true, do not retry it blindly.

Validation and migration

python -m pytest -q
python scripts/check_publication.py
python -m compileall -q src tests
python -m pip check

See integration/migration notes, the implementation plan, and the initial security review. No production connections or deployment are required to run the synthetic tests.

Available Tools

27 tools
check_cronB
Read-only

List cron jobs — user crontab and system /etc/cron.d/ entries.

Inputs: server (required), user.

check_portsB
Read-only

List all listening TCP ports and associated processes on a server.

Inputs: server (required).

check_servicesB
Read-only

Check systemd service status. Pass specific service names or omit for all running services.

Inputs: server (required), services.

check_updatesA
Read-only

Read available updates from the existing apt cache without refreshing it. Results may be stale.

Inputs: server (required), security_only.

connect_serverB
Read-only

Compatibility alias for start_session. New hosts are enrolled only through the operator CLI.

Inputs: server (required).

create_backupC
Destructive

Create a tar.gz backup of a directory. Auto-generates timestamped name if not provided.

Inputs: server (required), source (required), dest_dir (required), name.

disconnect_serverC
Destructive

Compatibility alias for end_session.

Inputs: server (required).

disk_usageC
Read-only

Get disk and filesystem usage for a server.

Inputs: server (required).

docker_composeB
Destructive

Run docker compose action in a directory. action: 'up', 'down', 'restart', 'stop', 'start', 'ps', 'logs', 'pull', 'build'.

Inputs: path (required), action (required), server (required).

docker_imagesC
Read-only

List Docker images on a server.

Inputs: server (required).

docker_logsC
Read-only

Get logs from a Docker container. Use tail to limit number of lines.

Inputs: server (required), container (required), tail.

docker_psA
Read-only

List Docker containers. Set all_containers=True to include stopped containers.

Inputs: server (required), all_containers.

edit_configA
Destructive

Read or atomically replace a regular config file. Writes require local permission; unique private backups are enabled by default.

Inputs: path (required), server (required), backup, content.

end_sessionB
Destructive

Close a cached SSH session. Verify remote completion before interrupting an active command.

Inputs: server (required).

execute_commandA
Destructive

Execute arbitrary shell code. Disabled by default; requires both local permission flags and client approval.

Inputs: server (required), command (required), timeout.

firewall_statusB
Read-only

Get UFW firewall status, default policies, and rules.

Inputs: server (required).

full_security_auditB
Read-only

Run a comprehensive security audit with scoring: SSH, firewall, users, network, filesystem, services, updates, logs, kernel, malware. Returns score, grade, findings, and markdown report.

Inputs: server (required).

generate_reportB
Read-only

Generate a comprehensive markdown report: system info, disk usage, ports, services.

Inputs: server (required).

install_packageA
Destructive

Install packages via apt on a remote server. Set update=False to skip apt update.

Inputs: server (required), packages (required), update.

list_backupsB
Read-only

List .tar.gz backup files in a directory with sizes and dates.

Inputs: path (required), server (required).

list_serversA
Read-only

List all configured servers and their connection status.

Inputs: no named parameters.

manage_serviceC
Destructive

Manage a systemd service. action: 'start', 'stop', 'restart', 'reload', 'enable', 'disable', 'status'.

Inputs: action (required), server (required), service (required).

operation_journalB
Read-only

Read bounded local metadata-only operation history; no command output or credentials are stored.

Inputs: limit, server, event_type.

process_listB
Read-only

List top processes sorted by CPU or memory usage. sort_by: 'cpu' or 'memory'.

Inputs: server (required), sort_by.

security_auditB
Read-only

Run a comprehensive security audit: SSH config, auto-updates, failed logins, root users, world-writable files.

Inputs: server (required).

start_sessionA
Read-only

Open a persistent SSH session using an existing operator-configured alias.

Inputs: server (required).

system_infoB
Read-only

Get OS, uptime, CPU cores, load average, memory and swap usage for a server.

Inputs: server (required).

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 27 tools

    Disambiguation2/5

    Several tools have explicitly overlapping purposes: connect_server/disconnect_server are documented aliases of start_session/end_session, security_audit and full_security_audit both run 'comprehensive security audits', and generate_report overlaps with both by emitting markdown reports. check_services also duplicates manage_service's 'status' action, and process_list vs check_services boundaries are fuzzy. An agent must read carefully to avoid picking the wrong variant.

    Naming Consistency3/5

    Two conventions coexist: verb_noun (list_servers, start_session, install_package, check_ports) and namespace_noun (docker_ps, docker_logs, process_list, firewall_status, system_info). Both are readable and snake_case is used throughout, but there is no single predictable pattern, and aliases like docker_ps use abbreviated verbs inconsistent with process_list.

    Tool Count2/5

    At 27 tools the surface is heavy for the stated purpose, and two alias pairs (connect/disconnect_server) plus the duplicate audit/report tools mean not every tool earns its place. Consolidation into a single session tool and one audit tool would cut roughly four entries with no loss of capability.

    Completeness4/5

    Coverage is broad: sessions, processes, packages, services, config editing, Docker, updates, firewall, security auditing, backups, cron, ports, disk, and a journal. Minor gaps remain — no backup restore/delete, no general log tailing outside Docker, and no user management — but agents can work around these via execute_command.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for remote Linux/Unix server management via SSH, enabling command execution, system monitoring, file operations, and diagnostics through natural language.
      34
      1
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for managing VPS servers via SSH, enabling command execution, file transfer, Docker management, and server documentation from within Claude.
      12 npm
      ISC
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server for Claude Code to execute commands on any remote server over SSH. Provides tools for remote execution, file operations, and connection info.
      1
      MIT