webmin-mcp-server
The Webmin MCP Server enables Claude to manage and monitor Linux systems through Webmin's administration interface, supporting multiple servers with a tiered safety framework.
Multi-Server Management: List configured Webmin servers, test connectivity, and retrieve version information.
System Monitoring: Get comprehensive system info (OS, kernel, CPU, memory, disk), memory usage, system time/timezone, runlevels, and running processes with CPU/memory stats.
Service Management: List, query, start, stop, restart, enable, and disable system services.
User & Group Administration: List users and groups; create, modify, and delete users; change passwords.
Scheduled Tasks (Cron): List, create, edit, and delete cron jobs.
Network: Retrieve network interface details, routing table, and default gateway.
Package Management: Get package info, list available updates, and count installed packages.
File Operations: Read, write, delete, copy, rename files, and create directories on remote systems.
Storage Management: Monitor disk usage, list mounted filesystems and physical disks, check SMART health, and manage LVM volume groups and logical volumes.
SSH: Access SSH server configuration and security settings.
Audit & Backup: View Webmin action/audit logs (filterable by user or module) and list configuration backups.
Security (Fail2ban): List jails, check their status, and view currently banned IPs.
Database (MySQL): List databases and users, and get MySQL server status/statistics.
Webmin ACL: List, view, create, modify, and delete Webmin user accounts; list available modules.
Disk Quotas: List quota-enabled filesystems, view user/group quotas, and set user quota limits.
Provides tools for listing MySQL databases, users, and server status.
Manages Linux systems via Webmin's administration interface, providing tools for system monitoring, service management, user/group administration, scheduled tasks, package management, file operations, storage, security, database management, and more.
Webmin MCP Server
An MCP (Model Context Protocol) server that provides Claude with tools to manage Linux systems via Webmin's administration interface.
Features
Multi-Server Support -- Manage multiple Webmin servers with user-friendly aliases
System Monitoring -- System info, memory, disk, network, and process status
Service Management -- Start, stop, restart, enable, and disable services
User & Group Administration -- Create, modify, and delete system users and groups
Scheduled Tasks -- View, create, edit, and delete cron jobs
Package Management -- Package info and available updates
File Operations -- Read, write, copy, rename, and delete remote files
Storage -- SMART disk health monitoring and LVM volume management
Security -- Fail2ban jail status and banned IP management
Database -- MySQL databases, users, and server status
Webmin ACL -- Manage Webmin user accounts and module permissions
Disk Quotas -- Monitor and set disk quota limits for users and groups
Audit & Backup -- Webmin action logs, SSH config, and configuration backups
Safety Framework -- Tiered safety system with safe mode to prevent dangerous operations
Related MCP server: CommandBridge MCP
Quick Start
Install (choose one):
From source:
git clone https://github.com/gjenkins20/webmin-mcp-server.git cd webmin-mcp-server pip install -e .With Docker:
docker pull gjenkins20/webmin-mcp-serverConfigure -- Create a
webmin-servers.json(see Configuration):{ "default_server": "my-server", "servers": { "my-server": { "host": "192.168.1.100", "port": 10000, "username": "admin", "password": "your-password", "use_https": true, "verify_ssl": false, "safe_mode": true } } }Add to Claude Desktop (
claude_desktop_config.json):From source:
{ "mcpServers": { "webmin": { "command": "python", "args": ["-m", "src.server"], "cwd": "/path/to/webmin-mcp-server", "env": { "WEBMIN_CONFIG_FILE": "/path/to/webmin-servers.json" } } } }With Docker:
{ "mcpServers": { "webmin": { "command": "docker", "args": [ "run", "--rm", "-i", "-v", "/path/to/webmin-servers.json:/app/webmin-servers.json:ro", "gjenkins20/webmin-mcp-server" ] } } }
Requirements
Python 3.11+
A running Webmin instance (typically on port 10000)
Webmin credentials with appropriate permissions
Webmin Server Setup
The MCP server uses Webmin's XML-RPC API. Ensure your Webmin server is configured:
Provision the service account:
Webmin 2.650+ (recommended): Create a dedicated RPC/API-only account in Webmin -> Webmin Users. This account type exists specifically for automation like this MCP server -- it blocks browser/module access entirely and is unaffected by the two-factor caveat below.
Older Webmin versions: In Webmin -> Webmin Users -> (your user) -> enable "Can accept RPC calls".
Two-factor authentication caveat: Webmin 2.640+ rejects RPC Basic-Auth requests for accounts that have 2FA enabled -- the RPC call fails with a generic 401/403. If you enable 2FA on your Webmin users, use a dedicated RPC/API-only account for this MCP server rather than a 2FA-enrolled one.
Install XML::Parser: The Perl XML::Parser module must be installed:
# Debian/Ubuntu sudo apt install libxml-parser-perl # RHEL/CentOS sudo yum install perl-XML-ParserModule Access: Grant the user access to required modules (System Status, Bootup and Shutdown, Users and Groups, Scheduled Cron Jobs, Network Configuration)
RPC timeout (optional): For tools that read/write large files, Webmin 2.620+ has a config option to raise the default RPC timeout (Webmin Configuration -> Advanced Options). Increase it if you see timeouts on large file operations.
Configuration
Multi-Server Configuration (Recommended)
Create a webmin-servers.json file to manage multiple Webmin servers. See webmin-servers.example.json for a complete example.
Configuration sources (priority order):
WEBMIN_CONFIG_FILEenv var -- path to JSON config fileWEBMIN_SERVERS_JSONenv var -- inline JSON string./webmin-servers.json-- local file in current directory~/.config/webmin-mcp/servers.json-- user config directoryLegacy
WEBMIN_*env vars -- single server (creates "default" alias)
Single Server Configuration (Legacy)
For a single server, set environment variables:
export WEBMIN_HOST="your-webmin-server.com"
export WEBMIN_PORT="10000"
export WEBMIN_USERNAME="admin"
export WEBMIN_PASSWORD="your-password"
export WEBMIN_USE_HTTPS="true"
export WEBMIN_VERIFY_SSL="true" # Set to false for self-signed certsOr create a .env file (see .env.example).
Using Multiple Servers
With multi-server configuration, all tools accept an optional server parameter:
"Get system info from pi1" -> Uses pi1 (default)
"Check disk usage on web-server" -> Uses web-server
"List services on server: nas" -> Uses nasUse list_webmin_servers to see all configured servers and their aliases.
Available Tools
All tools accept an optional server parameter to target a specific Webmin server. See the full API reference for detailed parameters and response formats.
Category | Tools | Description |
Server |
| Manage and test server connections |
System |
| System monitoring and information |
Services |
| Service lifecycle management |
Users & Groups |
| User and group administration |
Cron |
| Scheduled task management |
Network |
| Interface and routing details |
Packages |
| Package information and updates |
Files |
| Remote file operations |
Storage |
| Disk, mount, SMART, and LVM management |
SSH |
| SSH server configuration |
Audit |
| Action logs and backups |
Security |
| Fail2ban intrusion prevention |
Database |
| MySQL database management |
Webmin ACL |
| Webmin user and permission management |
Disk Quotas |
| Disk quota monitoring and management |
Safety Framework
The server includes a tiered safety system to prevent accidental damage.
Safety Tiers
Tier | Description | Safe Mode |
Read | No system changes | Always allowed |
Safe | Low-risk changes | Allowed |
Moderate | Reversible changes | May block critical services |
Dangerous | Destructive operations | Blocked |
Safe Mode
Safe mode is enabled by default. When active:
Dangerous operations are blocked (user creation/deletion, password changes, cron deletion)
Critical services (
ssh,webmin,systemd-*,dbus) cannot be stoppedFile writes/deletes are restricted to
/tmpand/var/tmpCritical system users and paths are protected
Configure per-server in webmin-servers.json:
{
"servers": {
"production": { "safe_mode": true },
"development": { "safe_mode": false }
}
}Or globally via environment: export WEBMIN_SAFE_MODE=false
Docker
Pull from Docker Hub
docker pull gjenkins20/webmin-mcp-serverBuild locally
docker build -t webmin-mcp-server .Run standalone
# With config file
docker run --rm -i \
-v /path/to/webmin-servers.json:/app/webmin-servers.json:ro \
gjenkins20/webmin-mcp-server
# With environment variables
docker run --rm -i \
-e WEBMIN_HOST=192.168.1.100 \
-e WEBMIN_USERNAME=admin \
-e WEBMIN_PASSWORD=your-password \
gjenkins20/webmin-mcp-serverTagging strategy
Tag | Description |
| Latest build from |
| Specific release version |
| Latest patch for minor version |
| Specific commit SHA |
Development
# Install with dev dependencies
pip install -e ".[dev]"
# Run tests
pytest
# Lint and format
ruff check src tests
ruff format src tests
# Type check
mypy srcSee CONTRIBUTING.md for guidelines on contributing to the project.
Project Structure
webmin-mcp-server/
├── src/
│ ├── server.py # MCP server setup
│ ├── webmin_client.py # Webmin API client
│ ├── config.py # Configuration management
│ ├── models.py # Pydantic models
│ └── tools/ # MCP tool implementations
├── tests/ # Test suite
├── docs/
│ ├── api-reference.md # Full API documentation
│ └── webmin_api_map.md # Webmin API endpoint mapping
├── .github/workflows/ # CI/CD (Docker build & push)
├── Dockerfile
└── webmin-servers.example.jsonLicense
Available Tools
61 toolschange_passwordA
Change a user's password. This is a dangerous operation and is blocked in safe mode.
Inputs: username (required), new_password (required), server.
copy_fileB
Copy a file to a new location. In safe mode, destination must be in /tmp or /var/tmp.
Inputs: source (required), destination (required), server.
create_cron_jobA
Create a new scheduled cron job. Specify the command to run and the schedule using cron syntax (minutes, hours, days, months, weekdays). Use '' for 'every' (e.g., '/5' for every 5 minutes).
Inputs: command (required), days, user, hours, +5 more.
create_directoryA
Create a new directory. In safe mode, only directories in /tmp or /var/tmp can be created.
Inputs: path (required), mode, server.
create_userA
Create a new system user. This is a dangerous operation and is blocked in safe mode.
Inputs: password (required), username (required), gid, uid, +4 more.
create_webmin_userA
Create a new Webmin user account. This is a dangerous operation and is blocked in safe mode.
Inputs: password (required), username (required), server, modules.
delete_cron_jobA
Delete a cron job. This is a dangerous operation and is blocked in safe mode. Use list_cron_jobs to find the job index.
Inputs: index (required), server.
delete_fileA
Delete a file or empty directory. This is a dangerous operation. In safe mode, only deletes in /tmp and /var/tmp are allowed. System directories are always protected.
Inputs: path (required), server.
delete_userA
Delete a system user. This is a dangerous operation and is blocked in safe mode. Critical system users cannot be deleted.
Inputs: username (required), server, delete_home.
delete_webmin_userA
Delete a Webmin user account. This is a dangerous operation and is blocked in safe mode. The last superuser account cannot be deleted regardless of safe mode.
Inputs: username (required), server.
disable_serviceA
Disable a service from starting automatically at system boot. Critical services are blocked to prevent boot failures.
Inputs: service (required), server.
edit_cron_jobA
Edit an existing cron job. Use list_cron_jobs to find the job index. Only specify the fields you want to change.
Inputs: index (required), days, user, hours, +6 more.
enable_serviceA
Enable a service to start automatically at system boot.
Inputs: service (required), server.
get_disk_healthA
Get SMART health status for a specific disk. Returns overall health, temperature, power-on hours, SMART attributes, and any errors or warnings.
Inputs: device (required), server.
get_disk_usageA
Get disk usage information for all mounted filesystems. Shows total, used, and free space, plus inode usage.
Inputs: server.
get_fail2ban_statusA
Get Fail2ban status for a specific jail or overall. Returns currently banned IPs and ban counts.
Inputs: jail, server.
get_group_quotaA
Get quota limits and usage for a specific group on a filesystem.
Inputs: group (required), filesystem (required), server.
get_memory_usageA
Get memory usage information. Shows total, used, and free memory in KB, MB, and GB, plus buffer and cache usage.
Inputs: server.
get_mysql_statusA
Get MySQL server status including version, uptime, connections, and query statistics.
Inputs: server.
get_network_infoB
Get network configuration including all interfaces (with IP, MAC, speed), routing table, and default gateway.
Inputs: server.
get_package_countA
Get the total count of installed packages on the system.
Inputs: server.
get_package_infoA
Get detailed information about an installed package including version, description, maintainer, and install date.
Inputs: package_name (required), server.
get_service_statusA
Get the status of a specific system service. Returns whether the service is running or stopped.
Inputs: service (required), server.
get_ssh_configB
Get SSH server (sshd) configuration settings including port, authentication methods, and security options.
Inputs: server.
get_system_infoA
Get comprehensive system information including OS, kernel, CPU, memory, disk usage, and update status. This is a good starting point for understanding system state.
Inputs: server.
get_system_timeA
Get the current system time and timezone configuration.
Inputs: server.
get_user_quotaB
Get quota limits and usage for a specific user on a filesystem.
Inputs: username (required), filesystem (required), server.
get_webmin_userB
Get detailed permissions for a specific Webmin user account. Shows which modules the user can access.
Inputs: username (required), server.
get_webmin_versionA
Get the version of the connected Webmin server. Returns the version string and hostname.
Inputs: server.
list_available_updatesB
List all available package updates including security updates. Shows current and new versions for each package.
Inputs: server.
list_backupsA
List Webmin configuration backups. Shows available backups that can be restored.
Inputs: server.
list_banned_ipsA
List all currently banned IP addresses from Fail2ban.
Inputs: jail, server.
list_cron_jobsA
List all scheduled cron jobs. Shows the schedule, command, user, and whether each job is active.
Inputs: server.
list_disksA
List all physical disks with SMART capability. Shows device path, model, serial number, capacity, and whether SMART is enabled.
Inputs: server.
list_fail2ban_jailsB
List all Fail2ban jails and their status. Shows which jails are enabled and their current ban counts.
Inputs: server.
list_groupsA
List all system groups. Returns both regular groups (GID >= 1000) and system groups separately, with member information.
Inputs: server.
list_logical_volumesB
List all LVM logical volumes. Shows name, size, volume group, device path, and mount point for each LV.
Inputs: server, volume_group.
list_mountsA
List all mounted filesystems. Shows mount point, device, filesystem type, and mount options.
Inputs: server.
list_mysql_databasesA
List all MySQL databases. Separates user databases from system databases (information_schema, mysql, etc.).
Inputs: server.
list_mysql_usersA
List all MySQL users and their host permissions.
Inputs: server.
list_processesA
List all running processes on the system. Shows PID, user, CPU usage, memory, and command for each process.
Inputs: server.
list_quota_filesystemsA
List filesystems with disk quota support. Shows which filesystems have quotas enabled and their status.
Inputs: server.
list_runlevelsB
List system runlevels and their descriptions.
Inputs: server.
list_servicesA
List all system services (systemd units or init scripts). Returns service names. Use get_service_status to check if a specific service is running.
Inputs: server.
list_user_quotasB
List all user quotas on a specific filesystem. Shows disk usage, soft/hard limits for blocks and files.
Inputs: filesystem (required), server.
list_usersA
List all system users. Returns both regular users (UID >= 1000) and system users separately, with details like home directory and shell.
Inputs: server.
list_volume_groupsA
List all LVM volume groups. Shows name, total size, free space, physical volume count, and logical volume count for each VG.
Inputs: server.
list_webmin_logsA
List Webmin action/audit logs. Shows recent actions performed through Webmin including user, module, and action details.
Inputs: user, limit, module, server.
list_webmin_modulesB
List all available Webmin modules that can be assigned to users.
Inputs: server.
list_webmin_serversA
List all configured Webmin servers with their aliases and connection info. Shows which server is the default.
Inputs: no named parameters.
list_webmin_usersA
List all Webmin user accounts (NOT system users). Shows usernames and which modules each user can access.
Inputs: server.
modify_userA
Modify an existing system user. Only specify fields you want to change.
Inputs: username (required), gid, uid, shell, +4 more.
modify_webmin_userA
Modify a Webmin user's permissions or password. This is a dangerous operation and is blocked in safe mode. Cannot demote the last superuser account.
Inputs: username (required), server, modules, password.
read_fileA
Read the contents of a file from the remote system. Can return content as a string or as an array of lines.
Inputs: path (required), server, as_lines.
rename_fileA
Rename or move a file. In safe mode, both source and destination must be in /tmp or /var/tmp.
Inputs: source (required), destination (required), server.
restart_serviceB
Restart a system service. The service will be stopped and then started again. Some critical services (ssh, webmin) may be blocked in safe mode.
Inputs: service (required), server.
set_user_quotaA
Set disk quota limits for a user on a filesystem. This is a dangerous operation and is blocked in safe mode. Set limits to 0 for unlimited.
Inputs: username (required), filesystem (required), server, hard_file_limit, +3 more.
start_serviceB
Start a stopped system service. If the service is already running, this is a no-op.
Inputs: service (required), server.
stop_serviceA
Stop a running system service. Critical services (ssh, webmin, systemd services) are blocked to prevent system lockout.
Inputs: service (required), server.
test_server_connectionA
Test connectivity to a specific Webmin server. Returns version and hostname if successful.
Inputs: server.
write_fileA
Write content to a file. This is a dangerous operation. In safe mode, only writes to /tmp and /var/tmp are allowed. System directories (/etc, /bin, /usr, etc.) are always blocked.
Inputs: path (required), content (required), server.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 61 tools
Each tool targets a specific resource and action, with clear distinctions between system users and Webmin users, file operations, cron jobs, services, etc. No two tools have overlapping purposes; even similar tools like get_disk_usage and list_mounts serve different informational needs.
Tool names follow a consistent verb_noun pattern throughout, using descriptive verbs like create, delete, list, get, modify, etc. The pattern is predictable, with verbs appropriately chosen for the action (e.g., list for collections, get for details).
With 61 tools, the set is overly large for a typical MCP server. Although the scope is broad (full server management via Webmin), the number exceeds what is considered manageable (25+), making the surface feel heavy and potentially overwhelming for agents.
The tool set covers most system administration tasks: user/group management, file operations, cron jobs, services, disk/memory/network monitoring, quotas, MySQL, Webmin configuration, etc. Minor gaps exist (e.g., no package install/remove, no firewall management), but core workflows are well-supported.
Maintenance
Related MCP Connectors
Linux server administration over OAuth MCP: shell, Docker, systemd, files and monitoring.
One MCP server for all your MCP servers: code mode, per-tool permissions, approvals and audit.
Secure Linux sandboxes for AI agents, as MCP tools.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceMCP server for the FortiMonitor v2 monitoring API. 241 tools across 33 modules covering server management, outage monitoring, maintenance windows, metrics, notifications, cloud monitoring, SNMP, dashboards, reporting, and more. Unofficial community project, not affiliated with Fortinet. Python, MIT license, Docker and local deployment supported.3MIT
- FlicenseAqualityBmaintenanceCross-platform MCP server for policy-controlled command execution on Linux and Windows, with no SSH dependency.3-
- FlicenseNot gradedqualityDmaintenanceA production-ready, modular MCP server with 40+ tools across 8 categories, featuring dynamic auto-loading and sandboxed security for file system, database, and network operations.-
- AlicenseNot gradedqualityBmaintenanceManage a fleet of OPNsense firewalls from an AI agent, inside guardrails it can't drive around. MCP server for central management of OPNsense firewall fleets. 129 tools across devices, config sync, tasks, schedules, templates, backups and remote consoles - destructive actions confirmation-gated, MCP-issued tokens lifetime-bounded, backup and storage secrets excluded from the toolset entirely.Apache 2.0