devbox-mcp

devbox-mcp is a minimal stdio MCP server for a personal development machine. It gives an MCP client terminal, process, and filesystem access with exactly the operating-system permissions of the user that runs it.

Threat model

This is intentionally a full-access personal devbox tool. It has no command allowlist, path restriction, read-only mode, approval layer, or sandbox. Running it as gurol allows MCP callers to do anything that gurol can do, but it does not bypass normal OS permissions or grant additional privileges.

The server does not provide authentication or a network listener. External access and authentication are the responsibility of the OpenAI Secure MCP Tunnel. systemd and Ansible deployment are managed in a separate repository.

Related MCP server: emcp

Usage

Node.js 24 or newer is required.

npm ci
npm run build
npm start

The server reads MCP JSON-RPC from stdin and writes only MCP protocol messages to stdout. Diagnostics, if any, go to stderr. It inherits the launching process environment and uses HOME as the default working directory.

Tools

• exec: run /bin/bash -c, returning stdout, stderr, exit status, timeout, and truncation details.

• process_start: start a long-running shell command and return an opaque process ID.

• process_status: inspect a managed process.

• process_output: page through bounded captured stdout/stderr with byte offsets.

• process_kill: terminate a managed process group.

• read_file: perform a bounded read, returning UTF-8 text or base64 binary data.

• write_file: write UTF-8 text, using atomic replacement for regular files when possible.

• list_directory: list one directory level with basic metadata.

• stat: inspect file, directory, or symlink metadata.

v0.1 limits

The process registry is in memory and is lost on server restart. Captured process output retains only the newest 2 MiB, exec retains at most 1 MiB per output stream, and individual file/process-output reads are limited to 1 MiB. Filesystem listing is deliberately non-recursive.