Skip to main content
Glama
JPeetz

Omarchy MCP Server

by JPeetz
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Omarchy MCP Server

A purpose-built Model Context Protocol server that runs on a Linux VM and exposes local AI agents and system tools as MCP tools — consumable by Hermes Agent or any MCP client.

Replaces SSH-based dispatch (fragile heredocs, ANSI scraping, plaintext passwords) with authenticated, structured MCP tool calls over Streamable HTTP.

Tools

Tool

Description

claude_execute(prompt, cwd?, timeout?)

Run Claude Code

codex_execute(prompt, cwd?, timeout?)

Run OpenAI Codex CLI

hermes_execute(prompt, cwd?, timeout?)

Run Hermes Agent

grok_execute(prompt, cwd?, timeout?)

Run xAI Grok CLI

file_read(path, offset?, limit?)

Read files on the remote VM

file_write(path, content, mode?)

Write files on the remote VM

file_list(path?)

List directories

system_run(command, cwd?, timeout?)

Run whitelisted shell commands

status()

VM health (uptime, memory, load, tool availability)

Each AI tool only appears in the tool list if its CLI binary is installed and on $PATH.

Related MCP server: AI Commander

Requirements

  • A Linux VM — tested on Arch / Omarchy. Works on any distro with Python 3.11+

  • Python 3.11+ with mcp>=2.0.0, psutil, uvicorn

  • Optional — AI agent CLIs on the VM (install at least one):

Deployment

1. Clone & Install Dependencies

git clone https://github.com/JPeetz/omarchy-mcp.git
cd omarchy-mcp
pip install -r requirements.txt

2. Configure

cp .env.example .env

# Generate a strong bearer token:
openssl rand -hex 32

# Edit .env — set OMARCHY_MCP_TOKEN to the generated value.
# Optionally set OMARCHY_USER_HOME if your home dir differs.
# For LAN access: set BIND=0.0.0.0 and configure TLS (see .env.example).

3. Start the Server

python3 server.py

The server starts on http://127.0.0.1:8911/mcp (loopback only) by default.

4. Verify Locally

curl -s -X POST http://127.0.0.1:8911/mcp \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-token>' \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2026-07-28","capabilities":{},"cientInfo":{"name":"test","version":"0.1"}}}'

Expected response starts with event: message followed by data: {"jsonrpc":...,"result":...}.

5. Systemd Service (Production)

# Edit omarchy-mcp.service to match your user/paths, then:
sudo cp omarchy-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now omarchy-mcp.service

The ExecStart, WorkingDirectory, User, and EnvironmentFile must match your system.

6. Connect Hermes Agent

On your desktop / control plane, add the server as an MCP connection:

hermes config set mcp_servers.omarchy.url "http://<vm-ip>:8911/mcp"
hermes config set mcp_servers.omarchy.headers.Authorization "Bearer <your-token>"

Replace <vm-ip> with the VM's LAN IP and <your-token> with your token.

Test:

hermes mcp test omarchy

Expected: ✓ Connected and ✓ Tools discovered: 9.

Call tools:

hermes -c "Cal the omarchy status tool and show me the result"

Environment Variables

Variable

Required

Default

Description

OMARCHY_MCP_TOKEN

Yes

—

Bearer token for MCP auth

PORT

No

8911

Server HTTP port

BIND

No

127.0.0.1

Bind address. 0.0.0.0 for LAN (with TLS)

TLS_CERT

No

—

Path to TLS certificate (enables HTTPS)

TLS_KEY

No

—

Path to TLS key file

OMARCHY_USER_HOME

No

os.expanduser(~)

User home for default working directory

OMARCHY_FILE_ROOTS

No

$HOME:/tmp

Colon-separated allowedpaths for file tools

Security

  1. Bearer token auth — every request requires Authorization: Bearer <token>. Constant-time comparison.

  2. Loopback by default — server binds to 127.0.0.1; network exposure is opt-in.

  3. TLS ready — set TLS_CERT/TLS_KEY for encrypted transport.

  4. Command whitelist — system_run only allows pre-approved commands.

  5. Path restriction — file tools only access user home and /tmp.

  6. Cancellation — request cancellation kills the entire subprocess group.

Troubleshooting

Symptom

Likely Cause

Fix

Connection refused

Server not running or wrong IP

Check systemctl status and BIND in .env

401 Unauthorized

Token mismatch

Regenerate token, update both sides

claude_execute not found

Claude Code not on VM

which claude — must be on $PATH

Command timed out

Agent took longer than timeout

Increase timeout parameter

License

MIT — see LICENSE.

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Codex Harness MCP

    2091k
    F
    license
    Not graded
    quality
    A
    maintenance
    Enables MCP-compatible AI clients to invoke CLI-driven agent tools over Streamable HTTP, including shell execution, file operations, patching, image viewing, web search, and nested agent tasks, with permission modes and real-time progress streaming.
    -

  • remote-access-mcp

    AmirAliManzar
    A
    license
    Not graded
    quality
    A
    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.
    1,013 npm
    4
    MIT

  • onputer

    tteggu87
    A
    license
    Not graded
    quality
    B
    maintenance
    Enables AI chat clients to securely access and manage local files, run terminal commands, work with Git repositories, and read AGENTS.md instructions and skills via a stateless Streamable HTTP MCP server.
    MIT