Skip to main content
Glama
Sign In
linux-harness-mcp

linux-harness-mcp

by EasonTechno
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

linux-harness-mcp

A Model Context Protocol server that exposes this host as a Linux harness over public-trusted HTTPS. Designed for AI agents that have no Linux runtime of their own — they connect and get shell, Python, and filesystem tools that execute here.

Features

  • 13 MCP tools: shell exec, Python exec, file read/write, directory ops, glob search, health check, opencode run/ultrawork

  • Basic Auth or Bearer Token authentication

  • Public HTTPS via ngrok (no certificate management needed)

  • One-command install with interactive wizard (lhm install)

  • Systemd service with auto-restart

  • CLI manager (lhm) for status, logs, config, diagnostics

Related MCP server: local-env-mcp

Quick Start

Install via npm

npm install -g linux-harness-mcp

Interactive Setup

sudo lhm install

This walks you through bind address, port, authentication, and optional ngrok exposure.

Check Status

lhm status

Get Public Endpoint

lhm url
# https://your-domain.ngrok-free.dev/mcp

CLI Reference (lhm)

Command

Description

lhm install

Interactive setup wizard

lhm uninstall

Stop + remove service + ngrok cleanup

lhm status

Show service status + public URL

lhm restart

Restart the service

lhm logs

View harness logs (-f to follow)

lhm logs --ngrok

View ngrok tunnel logs

lhm url

Print public MCP endpoint

lhm config

Show configuration (secrets masked)

lhm config --edit

Open config in $EDITOR

lhm doctor

Run health checks (incl. ngrok)

lhm version

Print version

MCP Tools

Tool

Description

shell_exec

Run shell commands via /bin/bash -c

python_exec

Execute Python scripts with system python3

file_read

Read files (auto text/binary, base64)

file_write

Write text or base64 binary files

list_dir

List directory entries with metadata

make_dir

Create directories (recursive)

delete_path

Delete files or directories

move_path

Move/rename paths

stat_path

Get file metadata (type, size, mode, mtime)

glob_search

Glob pattern file search

health_check

Service health + host summary

opencode_run

Execute complex tasks via opencode CLI

opencode_ultrawork

Execute tasks with ultrawork mode

Client Configuration

Basic Auth (recommended)

{
  "mcpServers": {
    "linux-harness": {
      "url": "https://your-domain.ngrok-free.dev/mcp",
      "headers": {
        "Authorization": "Basic <base64(user:pass)>",
        "ngrok-skip-browser-warning": "any"
      }
    }
  }
}

Bearer Token

{
  "mcpServers": {
    "linux-harness": {
      "url": "http://127.0.0.1:8765/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Architecture

Agent (MCP client)
  |  HTTPS (TLS 1.2/1.3, Let's Encrypt via ngrok)
  v
ngrok :443 --> 127.0.0.1:8765  (uvicorn + FastMCP Streamable HTTP)
                   |
                   v
               shell / python3 / filesystem  (as root)

  • Public ingress: ngrok tunnel to 127.0.0.1:8765

  • MCP transport: Streamable HTTP, stateful sessions

  • Auth: ASGI middleware (Basic Auth or Bearer Token)

  • /health: unauthenticated health endpoint

Environment Variables

Variable

Default

Description

HARNESS_HOST

127.0.0.1

Bind address

HARNESS_PORT

8765

Bind port

HARNESS_AUTH_USER

—

Basic Auth username

HARNESS_AUTH_PASS

—

Basic Auth password

HARNESS_TOKEN

—

Bearer token (alternative to Basic Auth)

HARNESS_ALLOWED_ORIGINS

—

Comma-separated allowed origins

Development

# Install in editable mode
pip install -e .

# Run tests
pytest tests/ -q

# Build wheel
python -m build --wheel

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    This server cannot be deployed

    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • remote-access-mcp

      AmirAliManzar
      A
      license
      Not graded
      quality
      B
      maintenance
      Turns any Linux server into an AI-agent-accessible machine over HTTPS, allowing MCP clients like ChatGPT, Claude, and Grok to securely control files, run shell commands, inspect system state, query SQLite, and work with git behind a bearer token.
      76 npm
      4
      MIT

    • Universal Host Manager MCP

      Abktya
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients such as ChatGPT and Claude to administer Linux or macOS hosts through authenticated Streamable HTTP, including running shell commands, reading and writing files within a workspace, listing directories, and retrieving system metrics.
      1
      MIT