MCP · filesystem + shell

Turn any computer into an MCP-controlled surface.

OpenHammer is a server that turns any computer into a secure, MCP-controlled surface. Run it on your laptop, or deploy it on a server to give any authenticated MCP client controlled filesystem and shell access. Connect Claude Desktop, Claude Code, Cursor, OpenCode, or your own client built on the MCP SDK. Whatever you connect gets read, write, search, and shell, all authenticated and scoped to a workspace. Local-first, and at scale it's a fleet of safe compute surfaces for AI.

$ npx openhammer@latest

MIT license Node 20+ No LLM inside, bring your own client Every connection authenticated

openhammer · 127.0.0.1:3000

any MCP client

Claude · Cursor · OpenCode · yours

tunnel (optional)

ngrok · cloudflare · 127.0.0.1

any computer

laptop · server · fleet

/mcp gate, 8 tools, bounded by MCP_ROOT_DIR and size caps, authenticated on every connection. One on your laptop, or a fleet across your servers.

The toolhead

Eight tools. That's the whole thing.

The best agents aren't buried under SDK abstractions. They're an LLM iterating over a filesystem with bash. OpenHammer serves exactly that surface and nothing else.

→guideRead-first orientation: the working-root contract and the tools.no params

→readRead a file, text or image.2000 lines / 50KB head

→bashRun a shell command. Merged stdout and stderr, full output spilled to a temp file.tail-truncated

→editExact-text replacement. Preserves BOM and CRLF, forgiving on whitespace and quotes.surgical

→writeCreate or overwrite a file. Parent dirs get created for you.mkdir -p built in

→grepripgrep content search, .gitignore-aware, NDJSON output.needs rg

→findfd file search by glob, .gitignore-aware.needs fd

→lsList a directory. Alphabetical, dotfiles included./ on dirs

Every response is bounded twice: per-tool truncation plus a universal 512KB backstop that emits a structured response_too_large block.

Quick start

From install to connected client in three moves.

Raise the hammer

# boot the control center
npx openhammer@latest

# first boot mints a bearer token into
# ~/.openhammer/credential.json (0600)

The TUI dashboard is the entrance. Status, channels, clients, monitor and doctor all live on one screen.

Point a client

{
  "mcpServers": {
    "openhammer": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer <token>"
      }
    }
  }
}

Any Streamable-HTTP MCP client works: Claude Desktop, Claude Code, Cursor, OpenCode, the MCP Inspector, or one you build with the @modelcontextprotocol/client SDK.

Reach a remote client

# add a tunnel channel
openhammer channel add
  # ngrok / cloudflare / static

# OAuth for Claude web and Code
openhammer auth set-login
openhammer auth add-client

export MCP_PUBLIC_URL=https://…

Live channels boot the tunnel with the server. OAuth discovery picks up the public URL on its own.

Gates & channels

Every path in is authenticated.

Whosoever holds this token, if they be worthy, shall possess the shell.

Three auth paths

Accepted in fall-through order at the /mcp gate.

bearer token · minted on first boot, constant-time compared

client credentials · id and secret for machine clients (HS256 JWT)

auth-code + PKCE · the login flow Claude web and Claude Code use

Three channel types

A channel is how a remote client reaches you.

ngrok · live tunnel, URL read from its inspector API

cloudflare · live quick-tunnel via cloudflared

static / nginx · you run the endpoint, OpenHammer probes /health

Real power, real guardrails.

OpenHammer exposes a powerful surface on purpose. A connected client can do anything the host user can, so every door has a lock: every connection is authenticated, every tool is bounded, and a container is the sandbox. Treat the bearer token like a password to the machine.

Bound the workspace : scope the file tools with MCP_ROOT_DIR

Never tunnel without auth : a public URL plus a weak token means internet shell access

Contain for isolation : mount only the target dir, the container is the sandbox

Know the limit : bash is not jailed, it reaches whatever your user can

The mead hall

Build with us.

Questions, harness designs, channel providers, weird tunneling setups. Bring them.

Ask · Show · Discuss