hatch-mcp

A minimal Model Context Protocol (MCP) server that exposes a single tool for executing allow-listed shell commands. The server is intended for scenarios where an agent must delegate a privileged command (such as xcodebuild) to a trusted helper outside of a sandboxed environment.

Prerequisites

• Node.js 18 or newer
• npm 9 or newer

Installation

# Clone the repository and install dependencies
npm install

# Build the TypeScript sources
npm run build

You can also run the server directly with npx ts-node src/index.ts during development if you have ts-node installed.

Launching the server

Provide the commands you want to allow at startup. Repeat --allow for each command or supply a comma-separated list via --allow-list (or the HATCH_MCP_ALLOW environment variable).

# Allow xcodebuild and cmake
npx hatch-mcp --allow xcodebuild --allow cmake

Additional examples:

# Using a comma-separated list
npx hatch-mcp --allow-list "xcodebuild,cmake"

# Using an environment variable
HATCH_MCP_ALLOW="xcodebuild" npx hatch-mcp

Tool interface

The server registers a single tool named run-allowed-command with the following schema:

• Input:
  • command (string, required): Shell command to execute. The executable must be present in the allow list supplied at launch.
  • outputFilePath (string, optional): Absolute or relative path where the formatted command report should be written. This lets agents capture the full output when a client UI truncates the text response. The file is created or overwritten.
• Output: Structured data containing the command, exit code, terminating signal (if any), captured stdout/stderr, and the outputFilePath (if provided). A formatted text summary is also returned for convenience.

Example invocation payload:

{
  "command": "xcodebuild -version",
  "outputFilePath": "./artifacts/xcodebuild-log.txt"
}

Safety restrictions

• Only commands whose executable name exactly matches an entry in the allow list will run.
• Composite commands are rejected. The server blocks pipes (|), command separators (;), logical operators (&&, ||), redirection (<, >), command substitution (` or $()), and multi-line input.
• Commands run without a shell using spawn, so normal shell expansions are unavailable.

Integrating with an MCP client

The server communicates over stdio. Configure your MCP-compatible client (e.g., Claude Desktop, Claude CLI, Cursor, or the MCP Inspector) to spawn the hatch-mcp binary with the desired allow list arguments.

Development scripts

• npm run build – compile TypeScript to JavaScript in dist/
• npm run lint – type-check the project without emitting output
• npm run clean – remove build artifacts

Contributions and improvements are welcome.