linux-mcp-server

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.

---

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 build

The built binary is at dist/index.js. You can also run it via:

node dist/index.js

Option 2 — Global install from source

npm install -g .
linux-mcp-server

---

Configuration

All configuration is via environment variables.

Core

| Variable | Default | Description | |---|---|---| | LOCAL_MODE | false | Set to true to manage the local machine directly (no SSH) | | TRANSPORT | stdio | Transport mode: stdio or http | | MCP_HTTP_PORT | 3300 | HTTP port (when TRANSPORT=http) | | MCP_HTTP_HOST | 127.0.0.1 | HTTP bind address (when TRANSPORT=http) | | COMMAND_TIMEOUT_MS | 30000 | Max time (ms) for any single command | | LOG_PATHS | /var/log | Comma-separated list of allowed log file path prefixes |

SSH mode only

| Variable | Required | Default | Description | |---|---|---|---| | SSH_HOST | Yes | — | Remote host IP or hostname | | SSH_USER | Yes | — | SSH username | | SSH_PORT | No | 22 | SSH port | | SSH_KEY_PATH | No | ~/.ssh/id_rsa | Path to private key | | SSH_STRICT_HOST_CHECK | No | true | Set to false to skip host key verification |

Sudo

| Variable | Description | |---|---| | SUDO_PASSWORD | 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.js

SSH 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.js

Run 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.target

Update 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.service

3. Enable linger (survive logout/reboot)

User services stop when you log out unless linger is enabled:

loginctl enable-linger $USER

Verify

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.js

Verify in Claude Code

/mcp

You 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 | |---|---| | run_command | Execute an arbitrary shell command. 30s timeout, 1MB output limit. | | run_command_sudo | Execute a shell command with sudo. Same limits. |

System

| Tool | Description | |---|---| | get_system_info | Hostname, OS version, kernel, uptime, architecture. | | get_cpu_usage | Load averages, core count, top process snapshot. | | get_memory_usage | RAM and swap usage. | | get_disk_usage | Disk usage per mount point and block device layout. | | get_network_interfaces | All interfaces with IPs and link state. |

Processes

| Tool | Description | |---|---| | list_processes | List running processes (ps aux), sortable by cpu/memory/pid. Returns top 60. | | get_process | Get details for a specific process by PID or name. | | get_top_processes | Top N processes by CPU or memory. | | kill_process | Send a signal to a process by PID. Default SIGTERM, use SIGKILL to force. |

Services

| Tool | Description | |---|---| | service_list | List systemd services. Filter by scope (system/user) and state. | | service_status | Get systemctl status for a service. | | service_start | Start a system service (sudo). | | service_stop | Stop a system service (sudo). | | service_restart | Restart a system service (sudo). | | service_enable | Enable a service to start at boot (sudo). | | service_disable | Disable a service from starting at boot (sudo). |

Files

| Tool | Description | |---|---| | read_file | Read file contents. 1MB limit. | | write_file | Write text to a file (create or overwrite). | | list_directory | List directory contents (ls -la). | | get_file_info | File metadata: permissions, owner, size, timestamps. | | make_directory | Create a directory (mkdir -p). | | delete_file | Delete a file or directory. Set recursive=true for non-empty dirs. |

Logs

| Tool | Description | |---|---| | get_journal_logs | Fetch systemd journal logs with filters (unit, since/until, lines, priority). | | tail_file | Tail a log file. Path must be under an allowed prefix (default: /var/log). | | search_logs | Search journal logs for a pattern. Optional unit filter. Returns last 200 matches. |

Packages (apt)

| Tool | Description | |---|---| | apt_list_installed | List installed packages. Optional name filter. | | apt_search | Search available packages by name or description. | | apt_show | Show detailed package information. | | apt_install | Install one or more packages (sudo). | | apt_remove | Remove packages, leaving config files (sudo). | | apt_update | Run apt-get update to refresh package index (sudo). | | apt_upgrade | 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 test

---

License

MIT