Linux Ssh

License: MIT Python 3.11 Docker

A Linux MCP server for remote administration over SSH. Diagnose, inspect, and manage any Linux host from Cursor, Claude Code, Codex, or any MCP (Model Context Protocol) client. Connects using per-user AD credentials elicited at runtime. Passwords live only in server memory with an idle TTL and are never logged.

• 45+ tools: filesystem, systemd services, Docker, JBoss/WildFly discovery and log search, network, certificates, firewall, and more
• Per-user AD identity: each request carries an X-AD-User header; the password is either supplied via the optional X-AD-Password header (no prompt) or elicited once and cached in-memory
• Optional sudo elevation: privileged commands require an explicit elevate_sudo call; the sudo password is prompted, or reuses X-AD-Password when supplied
• Zero secrets on disk: no credentials in config files, env vars, or logs

Example prompts

• "Why is the disk almost full on host1? What's eating the space?"
• "The myapp service keeps crashing, check the journal logs and tell me why."
• "Grep the JBoss server log for OutOfMemory errors from today."
• "Which process is listening on port 8443?"
• "Is the TLS certificate on host1:443 close to expiry?"
• "Tail the logs of the nginx Docker container."
• "Restart the httpd service and confirm it came back up."

Tools

Session

Tool	Description
connect	Open an SSH session to a Linux host and return a session_id
disconnect	Close an active SSH session
list_sessions	List active SSH sessions with usage details
elevate_sudo	Enable sudo for the session (password prompted once, cached in memory)

Filesystem (read-only)

Tool	Description
list_directory	List files with permissions, owner, size, and mtime
find_files	Recursively find files by name pattern
read_file	Read file contents as numbered lines via SFTP streaming
search_file_content	Grep for text in a file or recursively across a directory
file_info	JSON metadata for a file or directory
compare_files	Unified-style diff of two files

System diagnostics (read-only)

Tool	Description
get_system_info	OS, kernel, uptime, RAM, CPU count, timezone
get_disk_space	Disk space for all mounted filesystems
get_disk_usage	Disk usage by directory, largest first
list_processes	Processes sorted by CPU or memory
get_perf_snapshot	CPU load, memory, swap, disk I/O, top processes
get_services	systemd services summary or full status detail
get_journal_logs	systemd journal: service failures, crashes, system events
get_dmesg	Kernel ring buffer: OOM kills, I/O errors, hardware faults
get_open_files	File-descriptor usage ("too many open files" diagnosis)
get_tcp_connections	Active TCP connections with owning process
get_network_config	Interfaces, routing table, DNS servers
test_network	ICMP ping or TCP port test from the remote host
resolve_dns	DNS resolution from the remote server's perspective
get_environment_variables	Environment variables, optionally filtered
get_cron_jobs	User crontab and system cron directories
get_users	User accounts with recent logins
get_permissions	Permissions, ownership, and POSIX ACLs
get_certificates	TLS certificate details and days until expiry (file or endpoint)
get_firewall_rules	firewalld or iptables rules

Docker & JBoss (read-only)

Tool	Description
get_docker	Containers, logs, inspect, stats, and images
discover_jboss	Discover running JBoss EAP/WildFly JVMs and their paths
get_jboss_server_log	Search JBoss/WildFly logs for errors with filename context

Write operations (all require user confirmation)

Tool	Description
restart_service / stop_service / start_service	Manage systemd services with before/after state
kill_process	Force-kill a process by PID
copy_file / rename_file / move_file	File operations (no overwrite unless requested)
create_directory	mkdir -p with confirmation
delete_file / delete_directory	Delete with metadata/size shown in the prompt
compress_archive / extract_archive	Create or extract .tar.gz / .zip archives
invoke_http_request	HTTP request from the remote server via curl

Quick Start

docker compose -f docker-compose.yml -p linux-ssh-mcp up -d --build --force-recreate

Client setup

X-AD-User is required. X-AD-Password is optional: omit it and the server prompts for the password once via MCP elicitation, caching it in memory.

Cursor (mcp.json)

{
  "mcpServers": {
    "linux-ssh-mcp": {
      "type": "http",
      "url": "http://localhost:8006/mcp",
      "headers": {
        "X-AD-User": "<your-ad-username>",
        "X-AD-Password": "<your-ad-password>"
      }
    }
  }
}

Claude Code

claude mcp add --transport http linux-ssh-mcp http://localhost:8006/mcp \
  --header "X-AD-User: <your-ad-username>" \
  --header "X-AD-Password: <your-ad-password>"

Codex (~/.codex/config.toml)

[mcp_servers.linux-ssh-mcp]
url = "http://localhost:8006/mcp"
http_headers = { "X-AD-User" = "<your-ad-username>", "X-AD-Password" = "<your-ad-password>" }

Any other MCP client works the same way: point it at the streamable HTTP endpoint and pass the headers.