linux-mcp-server
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., "@linux-mcp-server check disk usage and memory status"
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.
linux-mcp-server
An MCP (Model Context Protocol) server for managing Ubuntu/Linux systems. Gives AI assistants like Claude direct access to system information, processes, services, files, logs, and package management — either on the local machine or a remote host via SSH.
What is this?
MCP is an open standard that lets AI assistants use tools — structured actions they can call to read data and take actions on real systems. Instead of copy-pasting terminal output into a chat window, an MCP server lets the AI query your system directly and act on what it finds.
linux-mcp-server exposes your Linux system as a set of MCP tools. You can point it at the machine it's running on (local mode) or at a remote host over SSH. Run one instance per host you want to manage.
Practical example: Rather than asking "how do I check if nginx is running?", your AI assistant can just check, see that it's failed, read the journal logs, and restart it — all without you copying a single line of output.
Related MCP server: mcp-ssh-multi
Features
Category | Tools |
Shell | Run arbitrary commands, run with sudo |
System | Hostname/OS info, CPU usage, memory usage, disk usage, network interfaces |
Processes | List processes, get process details, top CPU/memory consumers, kill process |
Services | List systemd services, status, start, stop, restart, enable, disable |
Files | Read, write, list directory, file info, create directory, delete |
Logs | Journal logs (with filters), tail log files, search journal by pattern |
Packages | List installed, search, show details, install, remove, apt update, upgrade |
Quick Start
Option 1 — Clone and build
git clone https://github.com/szoran53/linux-mcp-server.git
cd linux-mcp-server
npm install
npm run buildThe built binary is at dist/index.js. You can also run it via:
node dist/index.jsOption 2 — Global install from source
npm install -g .
linux-mcp-serverConfiguration
All configuration is via environment variables.
Core
Variable | Default | Description |
|
| Set to |
|
| Transport mode: |
|
| HTTP port (when |
|
| HTTP bind address (when |
|
| Max time (ms) for any single command |
|
| Comma-separated list of allowed log file path prefixes |
SSH mode only
Variable | Required | Default | Description |
| Yes | — | Remote host IP or hostname |
| Yes | — | SSH username |
| No |
| SSH port |
| No |
| Path to private key |
| No |
| Set to |
Sudo
Variable | Description |
| Optional. Provide if the SSH user requires a password for sudo. Not needed if the user has passwordless sudo. |
Modes
Local mode
Runs on the machine you want to manage. Commands execute directly — no SSH involved. Ideal for running as a systemd service on each host.
LOCAL_MODE=true TRANSPORT=http MCP_HTTP_PORT=3300 node dist/index.jsSSH mode
Connects to a remote host over SSH. Run the server anywhere (your workstation, a management box) and point it at a target.
SSH_HOST=192.168.1.50 \
SSH_USER=admin \
SSH_KEY_PATH=~/.ssh/id_ed25519 \
TRANSPORT=http \
MCP_HTTP_PORT=3301 \
node dist/index.jsRun multiple instances on different ports to manage multiple hosts simultaneously.
Running as a systemd service
The recommended approach for homelab use is a systemd user service — it runs under your user account, starts on boot, and restarts automatically.
1. Create the service file
Copy the example from the repo:
mkdir -p ~/.config/systemd/user
cp examples/mcp-linux-local.service ~/.config/systemd/user/Or create ~/.config/systemd/user/mcp-linux-local.service:
[Unit]
Description=Linux MCP Server (local - this machine)
After=network.target
[Service]
Type=simple
ExecStart=/usr/local/bin/linux-mcp-server
Restart=always
RestartSec=5
Environment=LOCAL_MODE=true
Environment=TRANSPORT=http
Environment=MCP_HTTP_PORT=3300
Environment=MCP_HTTP_HOST=127.0.0.1
[Install]
WantedBy=default.targetUpdate ExecStart to match where your binary is (which linux-mcp-server).
2. Enable and start
systemctl --user daemon-reload
systemctl --user enable mcp-linux-local.service
systemctl --user start mcp-linux-local.service
systemctl --user status mcp-linux-local.service3. Enable linger (survive logout/reboot)
User services stop when you log out unless linger is enabled:
loginctl enable-linger $USERVerify
curl http://localhost:3300/health
# {"status":"ok","server":"linux-mcp-server","version":"0.1.0"}Connecting to Claude Code
Claude Code is Anthropic's CLI for Claude. MCP servers are configured in ~/.claude.json (global) or per-project.
HTTP transport (recommended for persistent servers)
Add to ~/.claude.json under mcpServers at the global level, or under projects["/your/project"].mcpServers for project scope:
{
"mcpServers": {
"linux-local": {
"type": "http",
"url": "http://localhost:3300/mcp"
}
}
}For a remote host running in SSH mode on port 3301:
{
"mcpServers": {
"linux-local": {
"type": "http",
"url": "http://localhost:3300/mcp"
},
"linux-myserver": {
"type": "http",
"url": "http://localhost:3301/mcp"
}
}
}stdio transport
If you prefer stdio (no persistent process), use the claude mcp add command:
# Local mode
claude mcp add linux-local \
-e LOCAL_MODE=true \
-- node /path/to/linux-mcp-server/dist/index.js
# SSH mode
claude mcp add linux-myserver \
-e SSH_HOST=192.168.1.50 \
-e SSH_USER=admin \
-e SSH_KEY_PATH=~/.ssh/id_ed25519 \
-- node /path/to/linux-mcp-server/dist/index.jsVerify in Claude Code
/mcpYou should see linux-local (or your server name) listed as connected.
Other MCP Clients
Claude Desktop
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"linux-local": {
"command": "node",
"args": ["/path/to/linux-mcp-server/dist/index.js"],
"env": {
"LOCAL_MODE": "true"
}
}
}
}Cline (VS Code)
In VS Code settings (cline.mcpServers):
{
"linux-local": {
"command": "node",
"args": ["/path/to/linux-mcp-server/dist/index.js"],
"env": {
"LOCAL_MODE": "true"
}
}
}Cursor
Add to .cursor/mcp.json in your project or ~/.cursor/mcp.json globally:
{
"mcpServers": {
"linux-local": {
"command": "node",
"args": ["/path/to/linux-mcp-server/dist/index.js"],
"env": {
"LOCAL_MODE": "true"
}
}
}
}Continue.dev
Add to ~/.continue/config.json under experimental.modelContextProtocolServers:
{
"experimental": {
"modelContextProtocolServers": [
{
"transport": {
"type": "stdio",
"command": "node",
"args": ["/path/to/linux-mcp-server/dist/index.js"],
"env": {
"LOCAL_MODE": "true"
}
}
}
]
}
}Tool Reference
Shell
Tool | Description |
| Execute an arbitrary shell command. 30s timeout, 1MB output limit. |
| Execute a shell command with sudo. Same limits. |
System
Tool | Description |
| Hostname, OS version, kernel, uptime, architecture. |
| Load averages, core count, top process snapshot. |
| RAM and swap usage. |
| Disk usage per mount point and block device layout. |
| All interfaces with IPs and link state. |
Processes
Tool | Description |
| List running processes (ps aux), sortable by cpu/memory/pid. Returns top 60. |
| Get details for a specific process by PID or name. |
| Top N processes by CPU or memory. |
| Send a signal to a process by PID. Default SIGTERM, use SIGKILL to force. |
Services
Tool | Description |
| List systemd services. Filter by scope (system/user) and state. |
| Get systemctl status for a service. |
| Start a system service (sudo). |
| Stop a system service (sudo). |
| Restart a system service (sudo). |
| Enable a service to start at boot (sudo). |
| Disable a service from starting at boot (sudo). |
Files
Tool | Description |
| Read file contents. 1MB limit. |
| Write text to a file (create or overwrite). |
| List directory contents (ls -la). |
| File metadata: permissions, owner, size, timestamps. |
| Create a directory (mkdir -p). |
| Delete a file or directory. Set recursive=true for non-empty dirs. |
Logs
Tool | Description |
| Fetch systemd journal logs with filters (unit, since/until, lines, priority). |
| Tail a log file. Path must be under an allowed prefix (default: /var/log). |
| Search journal logs for a pattern. Optional unit filter. Returns last 200 matches. |
Packages (apt)
Tool | Description |
| List installed packages. Optional name filter. |
| Search available packages by name or description. |
| Show detailed package information. |
| Install one or more packages (sudo). |
| Remove packages, leaving config files (sudo). |
| Run apt-get update to refresh package index (sudo). |
| Upgrade installed packages (sudo). Supports dry_run=true. |
Roadmap
npm publish
SSH multi-host: multiple named SSH targets in a single server instance
ZFS module: pool status, scrub, snapshot management
GPU host support: nvidia-smi integration for CUDA hosts
README in other languages
Contributing
PRs welcome. The codebase is straightforward TypeScript — each tool category is a self-contained module in src/tools/. Tests use Vitest.
npm testLicense
MIT
Available Tools
47 toolsapt_installInstall PackagesA
Install one or more apt packages (runs apt-get install -y via sudo).
Inputs: packages (required).
apt_list_installedList Installed PackagesARead-only
List installed apt packages. Optional filter by name substring.
Inputs: filter.
apt_removeRemove PackagesADestructive
Remove one or more apt packages, leaving config files (apt-get remove). Use run_command_sudo for purge.
Inputs: packages (required).
apt_searchSearch PackagesARead-only
Search available apt packages by name or description.
Inputs: query (required).
apt_showShow Package DetailsBRead-only
Show detailed information about a package (apt-cache show).
Inputs: package (required).
apt_updateUpdate Package ListsB
Run apt-get update to refresh package index (sudo).
Inputs: no named parameters.
apt_upgradeUpgrade PackagesA
Upgrade installed packages (apt-get upgrade). Set dry_run=true to preview without applying.
Inputs: dry_run.
delete_fileDelete FileADestructive
Delete a file or directory. Set recursive=true to delete non-empty directories.
Inputs: path (required), recursive.
get_cpu_usageGet CPU UsageARead-only
Returns CPU load averages, core count, and a top snapshot.
Inputs: no named parameters.
get_disk_usageGet Disk UsageARead-only
Returns disk usage per mount point (df -h) and block device layout (lsblk).
Inputs: no named parameters.
get_file_infoGet File InfoBRead-only
Get file metadata: permissions, owner, size, timestamps (stat).
Inputs: path (required).
get_journal_logsGet Journal LogsBRead-only
Fetch systemd journal logs with optional filters. unit: service name, since/until: time range (e.g. "1 hour ago"), lines: count, priority: 0-7 or emerg/alert/crit/err/warning/notice/info/debug.
Inputs: unit, lines, since, until, +1 more.
get_memory_usageGet Memory UsageARead-only
Returns RAM and swap usage (free -h and /proc/meminfo).
Inputs: no named parameters.
get_network_interfacesGet Network InterfacesARead-onlyIdempotent
Returns all network interfaces with IPs and link status (ip addr, ip link).
Inputs: no named parameters.
get_processGet Process DetailsBRead-only
Get details about a specific process by PID or name.
Inputs: pid, name.
get_system_infoGet System InfoARead-onlyIdempotent
Returns hostname, OS version, kernel, uptime, and architecture.
Inputs: no named parameters.
get_top_processesGet Top ProcessesCRead-only
Get top N processes sorted by CPU or memory usage.
Inputs: count, sort_by.
kill_processKill ProcessADestructive
Send a signal to a process by PID. Default signal is SIGTERM (graceful). Use SIGKILL to force. Runs via sudo.
Inputs: pid (required), signal.
list_directoryList DirectoryBRead-only
List directory contents with details (ls -la).
Inputs: path (required).
list_processesList ProcessesARead-only
List running processes (ps aux), sorted by cpu, memory, or pid. Returns top 60.
Inputs: sort_by.
make_directoryMake DirectoryA
Create a directory (mkdir -p, creates parent dirs as needed).
Inputs: path (required).
read_fileRead FileBRead-only
Read the contents of a file. Subject to 1MB output limit.
Inputs: path (required).
run_commandRun CommandA
Execute an arbitrary shell command and return stdout/stderr. Subject to 30s timeout and 1MB output limit. Use for operations not covered by structured tools.
Inputs: command (required).
run_command_sudoRun Command (sudo)ADestructive
Execute an arbitrary shell command with sudo. Same limits as run_command. Use for privileged operations not covered by structured tools (e.g. apt purge, iptables).
Inputs: command (required).
search_logsSearch LogsARead-only
Search journal logs for a pattern (grep -i). Optional unit filter. Returns last 200 matching lines.
Inputs: pattern (required), unit.
service_disableDisable ServiceADestructive
Disable a system service from starting at boot (sudo). System scope only.
Inputs: name (required).
service_enableEnable ServiceA
Enable a system service to start at boot (sudo). System scope only.
Inputs: name (required).
service_listList ServicesBRead-only
List systemd services. scope: "system" (default) or "user". Optional state filter (e.g. "running", "failed").
Inputs: scope, state.
service_restartRestart ServiceA
Restart a system service (sudo). System scope only.
Inputs: name (required).
service_startStart ServiceA
Start a system service (sudo). System scope only.
Inputs: name (required).
service_statusGet Service StatusBRead-only
Get systemctl status for a named service.
Inputs: name (required), scope.
service_stopStop ServiceADestructive
Stop a system service (sudo). System scope only.
Inputs: name (required).
tail_fileTail Log FileBRead-only
Tail a log file. Path must start with an allowed prefix (default: /var/log).
Inputs: path (required), lines.
write_fileWrite FileADestructive
Write text content to a file (creates or overwrites). Text only — binary files are not supported. Requires appropriate filesystem permissions.
Inputs: path (required), content (required).
zfs_create_snapshotCreate ZFS SnapshotB
Create a ZFS snapshot (sudo). Use format dataset@snapname.
Inputs: snapshot (required).
zfs_destroy_snapshotDestroy ZFS SnapshotBDestructive
Permanently delete a ZFS snapshot (sudo, destructive).
Inputs: snapshot (required).
zfs_get_propertyGet ZFS PropertyARead-onlyIdempotent
Get one or more properties from a ZFS dataset or pool. Use "all" for all properties.
Inputs: name (required), property (required).
zfs_list_datasetsList ZFS DatasetsARead-onlyIdempotent
List ZFS datasets with used, available, compression, recordsize, and mount info. Optionally filter by pool.
Inputs: pool.
zfs_list_poolsList ZFS PoolsARead-onlyIdempotent
List all ZFS pools with size, allocation, fragmentation, health, and autotrim status.
Inputs: no named parameters.
zfs_list_snapshotsList ZFS SnapshotsBRead-onlyIdempotent
List ZFS snapshots with size and creation time, sorted by creation date.
Inputs: dataset.
zfs_pool_get_propertyGet ZFS Pool PropertyBRead-onlyIdempotent
Get a property from a ZFS pool (e.g. autotrim, ashift, health).
Inputs: pool (required), property (required).
zfs_pool_iostatZFS Pool I/O StatsARead-only
Show ZFS pool I/O statistics (ops, bandwidth, latency) sampled over 3 seconds.
Inputs: pool.
zfs_pool_set_propertySet ZFS Pool PropertyBIdempotent
Set a property on a ZFS pool (sudo), e.g. autotrim=on.
Inputs: pool (required), value (required), property (required).
zfs_pool_statusZFS Pool StatusARead-onlyIdempotent
Show detailed ZFS pool status including vdev tree, scrub results, and errors. Optionally filter to a specific pool.
Inputs: pool.
zfs_run_scrubRun ZFS ScrubA
Start a scrub on a ZFS pool to verify data integrity (sudo).
Inputs: pool (required).
zfs_set_propertySet ZFS PropertyBIdempotent
Set a property on a ZFS dataset (sudo).
Inputs: name (required), value (required), property (required).
zfs_stop_scrubStop ZFS ScrubA
Stop an in-progress scrub on a ZFS pool (sudo).
Inputs: pool (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 47 tools
Most tools target distinct resources, but there are overlapping pairs: zfs_get_property can read from pools while zfs_pool_get_property also does; list_processes and get_top_processes both return top processes; tail_file and search_logs/get_journal_logs overlap on logs. Descriptions mitigate some confusion but boundaries are not always crisp.
Naming is largely predictable with verb_noun or prefix_action patterns (apt_*, service_*, zfs_*). Minor inconsistencies exist like zfs_pool_status vs zfs_list_pools and zfs_pool_get_property vs zfs_get_property, but overall the set is readable and consistent.
47 tools is well above the 25-tool threshold for 'too many' despite covering many domains. The breadth may justify some tools, but the set feels heavy and could be consolidated (e.g., ZFS pool vs dataset property tools).
Covers system info, packages, services, files, commands, ZFS, logs, and processes—broad for Linux administration. Gaps like user management or network configuration can be handled via run_command, so core lifecycle is mostly complete.
Related MCP Connectors
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
Related MCP Servers
- FlicenseBqualityFmaintenanceAn MCP server that allows AI models to execute system commands on local machines or remote hosts via SSH, supporting persistent sessions and environment variables.128-
- AlicenseAqualityCmaintenanceMCP server for managing multiple SSH servers via AI assistants, offering tools for remote command execution, file operations, and system monitoring.1128 PyPI2MIT
- FlicenseCqualityBmaintenanceMCP server for remote Linux server administration via SSH, integrating with Claude Code to manage Ubuntu/Debian servers.272-

6amdev-server-mcpofficial
AlicenseBqualityDmaintenanceMCP server for managing Ubuntu servers with AI integration, enabling system monitoring, Docker control, Gitea repository management, Ollama LLM interaction, workspace file operations, and Claude Code assistant via natural language.34MIT