Client Configuration¶

Configure your MCP client - an AI application, to use the Linux MCP Server.

Environment Variables

Most configurations require environment variables for SSH connections and features. See the Configuration Reference for the full list of options.

MCP Client Configuration Examples

Claude Code
Claude Desktop
Codex
Cursor
Gemini CLI
Goose
opencode
VS Code / Copilot
Windsurf

Claude Code¶

Claude Code is Anthropic's official CLI tool.

Configuration¶

Edit ~/.claude.json:

uv (Recommended)Container (stdio transport)

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "podman",
      "args": [
        "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

Claude Desktop¶

Configuration File Location¶

Edit your Claude Desktop configuration file:

Linux: ~/.config/Claude/claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Configuration Examples¶

The value for command will vary depending on how linux-mcp-server was installed.

uv (Recommended)Container (stdio transport)

{
  "mcpServers": {
    "linux-diagnostics": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_ALLOWED_LOG_PATHS": "/var/log/messages,/var/log/lastlog"
      }
    }
  }
}

{
  "mcpServers": {
    "Linux Tools": {
      "command": "podman",
      "args": [
        "run",
        "--rm",
        "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username and adjust paths as needed.

Applying Configuration Changes¶

After editing the configuration file:

Restart Claude Desktop completely (quit and relaunch)
Look for the MCP server indicator in Claude Desktop
The server should appear in the list of available tools

Codex¶

Codex is OpenAI's CLI tool.

Configuration¶

Edit ~/.codex/config.toml:

uv (Recommended)Container (stdio transport)

[mcp_servers.linux-mcp-server]
command = "/home/YOUR_USER/.local/bin/linux-mcp-server"
args = []

[mcp_servers.linux-mcp-server.env]
LINUX_MCP_USER = "your-ssh-username"

[mcp_servers.linux-mcp-server]
command = "podman"
args = [
  "run", "--rm", "--interactive",
  "--userns", "keep-id:uid=1001,gid=0",
  "-e", "LINUX_MCP_KEY_PASSPHRASE",
  "-e", "LINUX_MCP_USER",
  "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
  "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
  "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
  "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
]

[mcp_servers.linux-mcp-server.env]
LINUX_MCP_KEY_PASSPHRASE = "<secret>"
LINUX_MCP_USER = "YOUR_USER"

Replace Paths

Replace YOUR_USER with your actual username.

Cursor¶

Cursor is an AI-powered code editor with MCP support.

Configuration¶

Edit ~/.cursor/mcp.json:

uv (Recommended)Container (stdio transport)

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "podman",
      "args": [
        "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

Gemini CLI¶

Gemini CLI is Google's command-line tool for Gemini.

Configuration¶

Edit ~/.gemini/settings.json:

uv (Recommended)Container (stdio transport)

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

Merging with Existing Settings

If you have other settings in your settings.json, add the mcpServers object alongside them.

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "podman",
      "args": [
        "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

Goose¶

Goose is Block's open-source AI agent. You can configure extensions via the GUI wizard or by editing the YAML config file directly.

GUI Wizard (Desktop App)¶

The Goose desktop app provides a wizard for adding extensions:

Open Goose and click the three dots menu (⋯) in the top-right corner
Select Settings → Extensions
Click Add custom extension

Fill in the fields:

Field	Value
Type	`Standard IO`
ID	`linux-tools`
Name	`linux-tools`
Description	`Linux system diagnostics`
Command	`/home/YOUR_USER/.local/bin/linux-mcp-server`
Arguments	(leave empty)
Environment Variables	`LINUX_MCP_USER=your-ssh-username`

Click Add to save the extension

Container Installation

For container-based installs, set Command to podman and add the container arguments in the Arguments field (one per line).

YAML Configuration (CLI)¶

If you prefer editing config files directly, add to ~/.config/goose/config.yaml:

uv (Recommended)Container (stdio transport)HTTP transport

extensions:
  linux-tools:
    enabled: true
    type: stdio
    name: linux-tools
    description: Linux tools
    cmd: /home/YOUR_USER/.local/bin/linux-mcp-server
    envs: {}
    env_keys:
      - LINUX_MCP_KEY_PASSPHRASE
      - LINUX_MCP_USER
    timeout: 30
    bundled: null
    available_tools: []
    args: []

extensions:
  linux-tools:
    enabled: true
    type: stdio
    name: linux-tools
    description: Linux tools
    cmd: podman
    args:
      - run
      - --rm
      - --interactive
      - --userns
      - "keep-id:uid=1001,gid=0"
      - -e
      - LINUX_MCP_KEY_PASSPHRASE
      - -e
      - LINUX_MCP_USER
      - -v
      - /home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro
      - -v
      - /home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z
      - -v
      - /home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw
      - quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest
    envs: {}
    env_keys:
      - LINUX_MCP_KEY_PASSPHRASE
      - LINUX_MCP_USER
    timeout: 30
    bundled: null
    available_tools: []

HTTP Transport Security

The HTTP transport does not currently have authentication. It should not be used in production or on untrusted networks.

Note

linux-mcp-server must be started separately when using HTTP transport.

extensions:
  linux-tools-http:
    enabled: true
    type: streamable_http
    name: linux-tools-http
    description: Linux Tools HTTP
    uri: http://localhost:8000/mcp
    envs: {}
    env_keys: []
    headers: {}
    timeout: 30
    bundled: null
    available_tools: []

Replace Paths

Replace YOUR_USER with your actual username and adjust paths as needed.

opencode¶

opencode is an AI-powered terminal coding assistant.

Configuration¶

Edit ~/.config/opencode/opencode.json:

uv (Recommended)Container (stdio transport)

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "linux-mcp-server": {
      "type": "local",
      "command": ["/home/YOUR_USER/.local/bin/linux-mcp-server"],
      "enabled": true,
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "linux-mcp-server": {
      "type": "local",
      "command": [
        "podman", "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "enabled": true,
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

VS Code / Copilot¶

VS Code with GitHub Copilot supports MCP servers in agent mode.

Configuration¶

Add to your VS Code mcp.json:

uv (Recommended)Container (stdio transport)

{
  "servers": {
    "linux-mcp-server": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

{
  "servers": {
    "linux-mcp-server": {
      "command": "podman",
      "args": [
        "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

Tip

Use the command palette (Ctrl+Shift+P) and search for "MCP" to manage servers.

Windsurf¶

Windsurf is Codeium's AI-powered IDE.

Configuration¶

Edit ~/.codeium/windsurf/mcp_config.json:

uv (Recommended)Container (stdio transport)

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "/home/YOUR_USER/.local/bin/linux-mcp-server",
      "args": [],
      "env": {
        "LINUX_MCP_USER": "your-ssh-username"
      }
    }
  }
}

{
  "mcpServers": {
    "linux-mcp-server": {
      "command": "podman",
      "args": [
        "run", "--rm", "--interactive",
        "--userns", "keep-id:uid=1001,gid=0",
        "-e", "LINUX_MCP_KEY_PASSPHRASE",
        "-e", "LINUX_MCP_USER",
        "-v", "/home/YOUR_USER/.ssh/id_ed25519:/var/lib/mcp/.ssh/id_ed25519:ro,Z",
        "-v", "/home/YOUR_USER/.ssh/config:/var/lib/mcp/.ssh/config:ro,Z",
        "-v", "/home/YOUR_USER/.local/share/linux-mcp-server/logs:/var/lib/mcp/.local/share/linux-mcp-server/logs:rw,Z",
        "quay.io/redhat-services-prod/rhel-lightspeed-tenant/linux-mcp-server:latest"
      ],
      "env": {
        "LINUX_MCP_KEY_PASSPHRASE": "<secret>",
        "LINUX_MCP_USER": "YOUR_USER"
      }
    }
  }
}

Replace Paths

Replace YOUR_USER with your actual username.

Other MCP Clients¶

The Linux MCP Server works with any MCP-compatible client. The general configuration pattern is:

Command: Path to linux-mcp-server executable (or podman/docker for container)
Arguments: Empty for native install, or container run arguments
Environment: Set variables as needed (see Configuration Reference)

Refer to your client's documentation for the specific configuration format.