machine-root-mcp

⚠ Personal use only. Do not deploy to a real server. See Security.

A self-hosted MCP (Model Context Protocol) server that gives AI coding assistants — Claude, Codex, or any MCP-compatible client — direct shell access to your local machine. One tool. Full access. No restrictions.

Built for personal local development workflows where you want AI to actually do things: run builds, read/write files, execute git commands, run tests, install packages, grep codebases — anything you'd type in a terminal.

What it is

An HTTP server implementing the Model Context Protocol spec with a single tool: run_command. When an AI client connects, it can call that tool with any bash command and get back stdout/stderr. That's it. No wrappers, no abstractions over the shell — just raw access.

The server handles full OAuth 2.0 Authorization Code + PKCE so any standard MCP client can connect using the discovery flow (/.well-known/oauth-authorization-server). OAuth state — registered clients, access tokens, refresh tokens — is persisted in a local SQLite database so registered clients survive server restarts without re-authenticating.

Related MCP server: Kontrol

What it does

• Exposes a single MCP tool: run_command(command, cwd, timeout)

• Implements a complete self-contained OAuth 2.0 authorization server (no external IdP)

• Supports dynamic client registration — AI clients register themselves automatically

• Serves a browser consent page when a client requests authorization

• Persists all OAuth state to SQLite (WAL mode) across restarts

• Logs every HTTP request, OAuth event, and tool call via structured pino logs

• Shuts down gracefully on SIGTERM/SIGINT (drains connections, closes DB)

What it will be used for

Running AI coding assistants against local projects as if they had a terminal open on your machine:

• Navigate and explore codebases (find, rg, cat, tree)

• Read, write, and edit source files

• Run builds, tests, and linters (pnpm build, vitest, eslint)

• Execute git operations (git log, git diff, git commit)

• Install dependencies, restart dev servers, tail logs

• Anything else you'd do in a terminal — because it literally is a terminal

The intent is to connect this to Claude or Codex as a persistent MCP server and let the AI operate on your local workspace without constant copy-pasting.

Stack

Quick start

git clone https://github.com/yugalkishor/machine-root-mcp
cd machine-root-mcp

pnpm install

# Build better-sqlite3 native binary (required once)
cd node_modules/better-sqlite3 && node_modules/.bin/prebuild-install && cd ../..

cp .env.example .env          # edit if needed
pnpm build
pnpm start

Server starts at http://localhost:3100.

Exposing publicly

To connect from a remote MCP client you need a public HTTPS URL. Deploy this on any server you have access to — a VPS (DigitalOcean, Hetzner, Linode), a home server with a static IP, or any machine you can put behind a reverse proxy (nginx, Caddy). Set BASE_URL in .env to your public HTTPS URL before building.

BASE_URL=https://your-server.com pnpm build && pnpm start

MCP endpoint: https://your-server.com/mcp

Environment variables

Security

This project is intentionally insecure. It is designed for local personal use only.

• run_command executes arbitrary shell commands with no blocklist, no sandboxing, and no path restrictions

• The OAuth server issues tokens to anyone who completes the consent flow

• SQLite tokens are stored unencrypted on disk

• There is no rate limiting, no audit log, no scope enforcement beyond the single mcp scope

Do not run this on a public server, a shared machine, or expose it without a tunnel you control. Whoever holds a valid access token has full shell access to your machine as your user.

License

Personal use. Not intended for distribution.