AgenSysAdmin
Allows remote administration of Debian servers via SSH, including system info, disk usage, service management, process monitoring, and command execution.
Allows remote administration of Linux servers via SSH, including system info, disk usage, service management, process monitoring, and command execution.
Allows remote administration of Ubuntu servers via SSH, including system info, disk usage, service management, process monitoring, and command execution.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@AgenSysAdmin check disk usage on production server"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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/workspaceUse 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_PASSWORDChoose 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 |
Package/service changes and backup creation |
|
Direct shell commands and Compose mutations | Both permission flags |
Config replacement | Both flags and exact path in |
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_hostsEnrollment 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 checkSee 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 toolscheck_cronBRead-only
List cron jobs — user crontab and system /etc/cron.d/ entries.
Inputs: server (required), user.
check_portsBRead-only
List all listening TCP ports and associated processes on a server.
Inputs: server (required).
check_servicesBRead-only
Check systemd service status. Pass specific service names or omit for all running services.
Inputs: server (required), services.
check_updatesARead-only
Read available updates from the existing apt cache without refreshing it. Results may be stale.
Inputs: server (required), security_only.
connect_serverBRead-only
Compatibility alias for start_session. New hosts are enrolled only through the operator CLI.
Inputs: server (required).
create_backupCDestructive
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_serverCDestructive
Compatibility alias for end_session.
Inputs: server (required).
disk_usageCRead-only
Get disk and filesystem usage for a server.
Inputs: server (required).
docker_composeBDestructive
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_imagesCRead-only
List Docker images on a server.
Inputs: server (required).
docker_logsCRead-only
Get logs from a Docker container. Use tail to limit number of lines.
Inputs: server (required), container (required), tail.
docker_psARead-only
List Docker containers. Set all_containers=True to include stopped containers.
Inputs: server (required), all_containers.
edit_configADestructive
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_sessionBDestructive
Close a cached SSH session. Verify remote completion before interrupting an active command.
Inputs: server (required).
execute_commandADestructive
Execute arbitrary shell code. Disabled by default; requires both local permission flags and client approval.
Inputs: server (required), command (required), timeout.
firewall_statusBRead-only
Get UFW firewall status, default policies, and rules.
Inputs: server (required).
full_security_auditBRead-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_reportBRead-only
Generate a comprehensive markdown report: system info, disk usage, ports, services.
Inputs: server (required).
install_packageADestructive
Install packages via apt on a remote server. Set update=False to skip apt update.
Inputs: server (required), packages (required), update.
list_backupsBRead-only
List .tar.gz backup files in a directory with sizes and dates.
Inputs: path (required), server (required).
list_serversARead-only
List all configured servers and their connection status.
Inputs: no named parameters.
manage_serviceCDestructive
Manage a systemd service. action: 'start', 'stop', 'restart', 'reload', 'enable', 'disable', 'status'.
Inputs: action (required), server (required), service (required).
operation_journalBRead-only
Read bounded local metadata-only operation history; no command output or credentials are stored.
Inputs: limit, server, event_type.
process_listBRead-only
List top processes sorted by CPU or memory usage. sort_by: 'cpu' or 'memory'.
Inputs: server (required), sort_by.
security_auditBRead-only
Run a comprehensive security audit: SSH config, auto-updates, failed logins, root users, world-writable files.
Inputs: server (required).
start_sessionARead-only
Open a persistent SSH session using an existing operator-configured alias.
Inputs: server (required).
system_infoBRead-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
Scored across 27 tools
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.
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.
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.
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
Related MCP Connectors
Connect ChatGPT and Claude to your Mac, Windows or Linux with secure MCP remote access.
Termalin's hosted MCP server. Claude, ChatGPT or any MCP client runs commands, moves files over SFTP, queries databases and reads server metrics and monitoring alerts on your servers, keylessly through Termalin Connectors: no SSH key is handed over and no inbound port is opened. Per-host command policy and an audit log. Needs a termal.in Pro or Team account (new accounts start with a 14-day Pro trial).
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server for remote Linux/Unix server management via SSH, enabling command execution, system monitoring, file operations, and diagnostics through natural language.341MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for managing VPS servers via SSH, enabling command execution, file transfer, Docker management, and server documentation from within Claude.12 npmISC
- AlicenseNot gradedqualityDmaintenanceMCP server for Claude Code to execute commands on any remote server over SSH. Provides tools for remote execution, file operations, and connection info.1MIT
- AlicenseBqualityDmaintenanceAn MCP server for managing Ubuntu/Linux systems, enabling AI assistants to execute commands, manage services, files, logs, and packages via local or SSH connection.47MIT