Skip to main content
Glama
EasonTechno

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: MCP Server

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

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

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Remote MCP Server

    OddbeakerLLC
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI tools like Claude to interact with a remote machine's file system and shell via a secure HTTPS endpoint. It provides standardized tools for executing shell commands, reading and writing files, and navigating directories.
    -

  • MCP Server

    sdirishguy
    F
    license
    Not graded
    quality
    C
    maintenance
    A secure Model Context Protocol server providing HTTP endpoints for AI agent tool execution, including file system operations, shell commands, and LLM-based code generation.
    1
    -