# Local MCP companion setup

The local MCP companion uses stdio and launches a fresh local browser. It processes image pixels with the same browser engine as the workbench; the Node process transports local files and does not transform them.

## Requirements and build

Use Node.js 22.23.4 or a compatible Node 22 release. In a checkout of the project, run npm ci, then build the workbench and local companion with npm run build:workbench, npm run build:runner, and npm run build --workspace @local-image-tools/mcp-local. Install Playwright Chromium with npx playwright install chromium.

## MCP host configuration

Configure the host to launch node /absolute/path/to/packages/mcp-local/dist/cli.js over stdio. Set LOCAL_IMAGE_INPUT_ROOTS to a path-delimited list of allowed input directories and LOCAL_IMAGE_OUTPUT_ROOT to the output directory. Tool calls cannot choose or expand these roots. Keep the process local; it does not connect to a hosted image-processing service.

## Available operations and limits

The local server provides import, the six image operations, explicit artifact export and release, status, and dedicated bounded batch tools. Batch import accepts up to 50 files, up to 20 MiB each and 100 MiB aggregate including an optional shared logo. Per-image processing is limited to 16 megapixels, 8,192 pixels per side, and 100 MiB output; retained batch outputs have a 100 MiB aggregate limit.

Export creates new files under the configured output root and does not overwrite originals. The MCP host and selected AI provider can see imported paths, arguments, filenames, and returned metadata. Image bytes and pixels are not included in model results by default.

See the repository docs/setup.md for complete development and deployment instructions and [the API guide](/developers.md) for catalog schemas and browser execution details.