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.

---

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

Layer	Technology
Runtime	Node.js 24
Language	TypeScript (ESM, strict)
HTTP server	Express 5
MCP protocol	@modelcontextprotocol/sdk
OAuth 2.0	Built-in (Authorization Code + PKCE)
Persistence	SQLite via better-sqlite3 (WAL)
Logging	pino + pino-pretty
Package manager	pnpm

---

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

Variable	Default	Description
PORT	3100	HTTP listen port
BASE_URL	http://localhost:3100	Public base URL (set to your public server URL)
MCP_DB_PATH	./data/local-mcp.db	SQLite database path
LOG_LEVEL	info	trace / debug / info / warn / error / fatal
NODE_ENV	development	development = pretty logs, production = JSON logs

---

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.