localmcp

A local MCP server for AI coding workflows. It gives ChatGPT a constrained view of one project directory plus the tools needed to inspect, edit, test, commit, and push code.

What it can do

localmcp exposes 11 tools:

• workspace_info — server, workspace, mode, and tool diagnostics

• list_files — list a directory

• tree — recursively inspect the workspace with depth and entry limits

• search_files — substring or regex search with globs and context lines

• read_file — read a whole file or a numbered line range

• write_file — create or replace a file

• edit_file — guarded exact-text replacement

• apply_patch — atomically apply multiple guarded edits to one file

• delete_file — delete a file

• move_file — move or rename a file

• run_command — execute a program directly without a shell

Together these are enough for a coding-agent loop such as:

inspect → search → read → edit → test → diff → commit → push

Workspace traversal respects the root .gitignore by default, and .git is always excluded.

Related MCP server: Kastor

Security model

All localmcp file tools are confined to LOCALMCP_ROOT. Absolute paths, .. traversal, and symbolic-link escapes are rejected.

Command execution has two modes.

Strict mode

strict is the default. run_command only accepts executables listed in LOCALMCP_ALLOWED_COMMANDS.

LOCALMCP_ROOT="$HOME/src/my-project" \
LOCALMCP_MODE=strict \
LOCALMCP_ALLOWED_COMMANDS="git,node,npm" \
npm start

With an empty allowlist, command execution is effectively disabled.

YOLO mode

For a trusted coding workspace, yolo removes the executable allowlist:

LOCALMCP_ROOT="$HOME/src/my-project" \
LOCALMCP_MODE=yolo \
npm start

localmcp still requires the command cwd to resolve inside LOCALMCP_ROOT.

YOLO mode is not an OS sandbox. An executed program can still read or modify files outside the workspace, access the network, spawn other processes, or execute code with the permissions of the localmcp process. Use an OS/container sandbox if you need process-level isolation.

Commands use Node.js spawn(..., { shell: false }), so localmcp does not wrap command input in a shell.

Requirements

• Node.js 18+

• Any command-line tools you want to execute must be installed and available on PATH

Install

npm install

Run

macOS/Linux:

LOCALMCP_ROOT="$HOME/src/my-project" npm start

PowerShell:

$env:LOCALMCP_ROOT = "C:\src\my-project"
npm start

The default mode is strict.

Open http://127.0.0.1:8787/ for the read-only status dashboard. It shows the current execution mode, workspace, MCP endpoint, command access, and runtime limits.

The MCP endpoint is:

http://127.0.0.1:8787/mcp

Server-side tool logs

Every MCP tool call is logged to stderr with its tool name, status, duration, and summarized input:

[localmcp] 2026-10-01T05:50:55.635Z tool=tree status=ok duration_ms=7.5 input={"path":".","max_depth":1,"max_entries":20,"respect_gitignore":true}

Large edit/file contents are summarized instead of being printed verbatim. These logs make it possible to follow the sequence of actions an AI client performs against the workspace.

Configuration

• PORT — HTTP port (default 8787)

• LOCALMCP_ROOT — exposed workspace root (default: current directory)

• LOCALMCP_MODE — execution mode: strict (default) or yolo

• LOCALMCP_ALLOWED_COMMANDS — comma-separated executable allowlist used by strict mode (default: empty)

• LOCALMCP_TIMEOUT_MS — command timeout (default 120000)

• LOCALMCP_MAX_OUTPUT — maximum chars captured per stdout/stderr stream (default 200000)

• LOCALMCP_MAX_FILE — maximum file size in bytes (default 1000000)

Test

npm test

The test suite covers workspace path confinement, symlink escape rejection, command allowlisting, dashboard rendering, gitignore-aware traversal, search, line slicing, guarded edits, and multi-edit patching.

Test with MCP Inspector

npx @modelcontextprotocol/inspector@latest

Choose Streamable HTTP and connect to http://127.0.0.1:8787/mcp.

Connect to ChatGPT

ChatGPT needs a reachable HTTPS /mcp URL. For development, expose port 8787 with a tunnel and use the resulting HTTPS URL ending in /mcp.

A public tunnel creates an entry point to your machine. Keep LOCALMCP_ROOT narrow and use strict mode unless you intentionally want unrestricted executable selection.