mcp-local

Local MCP server over Streamable HTTP with two tools:

• get_server_metadata
• run_command

Requirements

• Node.js 20+
• ngrok access is required for both development and production startup

Install

npm install

Run

Development:

npm run dev

Production build:

npm run build
npm start

Published package:

npx mcp-local <flags>

The server listens on http://127.0.0.1:3000/mcp. It also exposes http://127.0.0.1:3000/health.

Every MCP request must include the x-auth-token header. The token is stored securely in the OS credential store via keytar, remains stable across restarts, and is printed to the console every time the server starts.

Refresh the stored token with:

npm run token:refresh

ngrok bootstrap

Both npm run dev, npm start, and npx mcp-local perform an ngrok bootstrap before the MCP server is considered ready:

1. Check whether ngrok is installed.
2. If it is missing:
   • macOS: run brew install ngrok
   • Windows: run winget install ngrok -s msstore
3. Validate the global ngrok authtoken by starting a short-lived ngrok http 3000 tunnel.
4. If the token is missing or invalid:
   • open the ngrok authtoken page
   • wait for you to paste the token into the terminal
   • save it with ngrok config add-authtoken <token>
   • retry until validation succeeds

The long-lived runtime tunnel always uses ngrok http 3000. Reserved-domain startup via NGROK_DOMAIN is no longer supported.

Non-interactive shells

• If ngrok is already installed and its global authtoken is valid, startup can proceed normally.
• If startup needs interactive token setup and no TTY is available, the process exits with a clear error.
• Automatic ngrok installation is only implemented for macOS and Windows. Other platforms must provide ngrok on PATH before startup.

CLI flags

• -h, --help
  • Prints CLI usage and exits without starting ngrok or the MCP server.
• --include <path>
  • Repeatable. Restricts run_command.cwd to one or more allowed root directories.
• --exclude <path>
  • Repeatable. Blocks run_command.cwd inside one or more root directories.
• --allow <command>
  • Repeatable. Restricts run_command.command to one or more allowed executables.
• --disallow <command>
  • Repeatable. Blocks one or more executables even if they are otherwise allowed.

Examples:

npm run dev -- --include C:\Users\m0o06\Downloads\projects --include D:\tmp
npm run dev -- --include C:\Users\m0o06\Downloads\projects --exclude C:\Users\m0o06\Downloads\projects\private
npm run dev -- --allow node --allow git --disallow git
npx mcp-local --include C:\Users\m0o06\Downloads\projects --allow node

When ngrok starts successfully, startup logs print the public ngrok URLs for:

• /mcp
• /health

They also always print the current x-auth-token.

Authentication

• x-auth-token is mandatory for /mcp.
• /health is intentionally public.
• The token is generated once and then reused on later runs.
• The token stays the same until you run npm run token:refresh.
• Tokens are stored securely with keytar.

Tools

get_server_metadata

Returns structured metadata about the host and runtime, including:

• platform
• type
• release
• version
• arch
• hostname
• nodeVersion
• cwd
• authEnabled
• scopes
• excludedScopes
• allowedCommands
• disallowedCommands

run_command

Input:

{
  "command": "node",
  "args": ["-e", "console.log('hello')"],
  "cwd": "C:\\Users\\m0o06\\Downloads\\projects\\local-mcp",
  "timeoutMs": 30000
}

Output:

{
  "command": "node",
  "args": ["-e", "console.log('hello')"],
  "cwd": "C:\\Users\\m0o06\\Downloads\\projects\\local-mcp",
  "exitCode": 0,
  "signal": null,
  "stdout": "hello\n",
  "stderr": "",
  "durationMs": 18,
  "timedOut": false
}

Notes:

• Commands run with child_process.spawn and shell: false.
• This server accepts structured command + args, not a raw shell string.
• Shell built-ins are not treated specially.
• If cwd is omitted, execution defaults to the first configured --include, or process.cwd() if no includes are configured.
• --exclude takes precedence over --include.
• --disallow takes precedence over --allow.
• Default timeout is 30 seconds. Maximum timeout is 300 seconds.

Test

npm test