Skip to main content
Glama
linux-mcp-server
by szoran53

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.

License: MIT Version


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

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

Available Tools

47 tools
apt_installInstall PackagesA

Install one or more apt packages (runs apt-get install -y via sudo).

Inputs: packages (required).

apt_list_installedList Installed PackagesA
Read-only

List installed apt packages. Optional filter by name substring.

Inputs: filter.

apt_removeRemove PackagesA
Destructive

Remove one or more apt packages, leaving config files (apt-get remove). Use run_command_sudo for purge.

Inputs: packages (required).

apt_showShow Package DetailsB
Read-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 FileA
Destructive

Delete a file or directory. Set recursive=true to delete non-empty directories.

Inputs: path (required), recursive.

get_cpu_usageGet CPU UsageA
Read-only

Returns CPU load averages, core count, and a top snapshot.

Inputs: no named parameters.

get_disk_usageGet Disk UsageA
Read-only

Returns disk usage per mount point (df -h) and block device layout (lsblk).

Inputs: no named parameters.

get_file_infoGet File InfoB
Read-only

Get file metadata: permissions, owner, size, timestamps (stat).

Inputs: path (required).

get_journal_logsGet Journal LogsB
Read-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 UsageA
Read-only

Returns RAM and swap usage (free -h and /proc/meminfo).

Inputs: no named parameters.

get_network_interfacesGet Network InterfacesA
Read-onlyIdempotent

Returns all network interfaces with IPs and link status (ip addr, ip link).

Inputs: no named parameters.

get_processGet Process DetailsB
Read-only

Get details about a specific process by PID or name.

Inputs: pid, name.

get_system_infoGet System InfoA
Read-onlyIdempotent

Returns hostname, OS version, kernel, uptime, and architecture.

Inputs: no named parameters.

get_top_processesGet Top ProcessesC
Read-only

Get top N processes sorted by CPU or memory usage.

Inputs: count, sort_by.

kill_processKill ProcessA
Destructive

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 DirectoryB
Read-only

List directory contents with details (ls -la).

Inputs: path (required).

list_processesList ProcessesA
Read-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 FileB
Read-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)A
Destructive

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 LogsA
Read-only

Search journal logs for a pattern (grep -i). Optional unit filter. Returns last 200 matching lines.

Inputs: pattern (required), unit.

service_disableDisable ServiceA
Destructive

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 ServicesB
Read-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 StatusB
Read-only

Get systemctl status for a named service.

Inputs: name (required), scope.

service_stopStop ServiceA
Destructive

Stop a system service (sudo). System scope only.

Inputs: name (required).

tail_fileTail Log FileB
Read-only

Tail a log file. Path must start with an allowed prefix (default: /var/log).

Inputs: path (required), lines.

write_fileWrite FileA
Destructive

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 SnapshotB
Destructive

Permanently delete a ZFS snapshot (sudo, destructive).

Inputs: snapshot (required).

zfs_get_propertyGet ZFS PropertyA
Read-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 DatasetsA
Read-onlyIdempotent

List ZFS datasets with used, available, compression, recordsize, and mount info. Optionally filter by pool.

Inputs: pool.

zfs_list_poolsList ZFS PoolsA
Read-onlyIdempotent

List all ZFS pools with size, allocation, fragmentation, health, and autotrim status.

Inputs: no named parameters.

zfs_list_snapshotsList ZFS SnapshotsB
Read-onlyIdempotent

List ZFS snapshots with size and creation time, sorted by creation date.

Inputs: dataset.

zfs_pool_get_propertyGet ZFS Pool PropertyB
Read-onlyIdempotent

Get a property from a ZFS pool (e.g. autotrim, ashift, health).

Inputs: pool (required), property (required).

zfs_pool_iostatZFS Pool I/O StatsA
Read-only

Show ZFS pool I/O statistics (ops, bandwidth, latency) sampled over 3 seconds.

Inputs: pool.

zfs_pool_set_propertySet ZFS Pool PropertyB
Idempotent

Set a property on a ZFS pool (sudo), e.g. autotrim=on.

Inputs: pool (required), value (required), property (required).

zfs_pool_statusZFS Pool StatusA
Read-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 PropertyB
Idempotent

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

    B3.3/5.0

    Scored across 47 tools

    Disambiguation3/5

    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 Consistency4/5

    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.

    Tool Count2/5

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

    Completeness4/5

    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

    Related MCP Servers

    • F
      license
      B
      quality
      F
      maintenance
      An MCP server that allows AI models to execute system commands on local machines or remote hosts via SSH, supporting persistent sessions and environment variables.
      1
      28
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server for managing multiple SSH servers via AI assistants, offering tools for remote command execution, file operations, and system monitoring.
      11
      28 PyPI
      2
      MIT
    • F
      license
      C
      quality
      B
      maintenance
      MCP server for remote Linux server administration via SSH, integrating with Claude Code to manage Ubuntu/Debian servers.
      27
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP 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.
      34
      MIT