Isolator MCP Server
isolator-mcp is a Model Context Protocol (MCP) server written in TypeScript. It acts as a wrapper around the embedded isolator Go CLI tool, providing a secure code execution sandbox accessible via MCP.
LLM applications (MCP Hosts) can connect to this server and use its execute_code tool to safely run Python, Go, or JavaScript code snippets provided directly or loaded from predefined snippet files.
Features
- Provides the
execute_codeMCP tool. - Supports executing code provided directly (
language,entrypoint_code) or via named snippets (snippet_name). - Supports multiple languages (Python, Go, JavaScript, configurable).
- Uses the embedded
isolatorGo CLI (isolator-cli/) for secure Docker container execution. - Configurable security defaults (timeout, resource limits, network) via
isolator_config.json. - Manages temporary directories on the host for code execution.
- Handles file copying into containers (by instructing the
isolatorCLI). - Returns structured results (stdout, stderr, status) via MCP, setting
isError: trueon tool-level failures.
Prerequisites
- Docker: Required for container creation and execution by the
isolator-cli. Ensure the Docker daemon is running. - Go: Required to build the embedded
isolator-cliGo binary. - Node.js and npm: Required to install dependencies, build, and run the
isolator-mcpTypeScript server.
Installation
- Build
isolatorGo CLI: Navigate to the embedded Go CLI directory and build the binary:cd isolator-cli go build -o isolator main.go cd .../isolator-cli/isolatorexecutable needed by the server. - Configure
isolator-mcp:- Edit
isolator_config.json: UpdateisolatorPathto point to the absolute path of the built binary (e.g.,/Users/ompragash/Documents/Cline/MCP/isolator-mcp/isolator-cli/isolator). Adjust default limits, container workdir, language images, or thepromptsDir(used for snippets) location if needed. - Ensure the
promptsdirectory exists (default:./prompts). Add code snippet files (e.g.,hello_world.py). The filename base (e.g.,hello_world) is used as thesnippet_name.
- Edit
- Install Server Dependencies: Navigate to the main directory (
isolator-mcp) and run:npm install - Build Server: Compile the TypeScript code:
This creates the executable script atnpm run buildbuild/index.js. - Configure MCP Host: Add the server to your MCP client's settings file (e.g.,
cline_mcp_settings.jsonfor the VS Code extension):{ "mcpServers": { "isolator": { "command": "node", "args": ["/Users/ompragash/Documents/Cline/MCP/isolator-mcp/build/index.js"], "env": {}, "disabled": false, "autoApprove": [] } } }argsif necessary). The MCP Host should automatically detect and start the server.
Important Note: Ensure the Docker images specified in isolator_config.json (e.g., python:3.11-alpine, golang:1.21-alpine) are pulled onto your system beforehand using docker pull <image_name>. The isolator tool does not automatically download missing images.
Local Development / Testing
To run the server locally for development or testing (without installing it via MCP Host settings):
- Build Go CLI: Ensure the
isolatorGo CLI is built within its subdirectory:cd isolator-cli go build -o isolator main.go cd .. - Build TS Server: In this main directory (
isolator-mcp), runnpm installandnpm run build. - Configure: Make sure
isolator_config.jsoncorrectly points to the built./isolator-cli/isolatorbinary via theisolatorPathkey (use the absolute path). - Run Server: Execute the built server directly using Node:
The server will start, connect via stdio, and print logs (includingnode build/index.jsconsole.errormessages fromindex.ts) to the console. - Interact (Manual): You can manually send JSON-RPC messages (e.g.,
tools/list,tools/call) to the server's standard input to test its responses. Tools like@modelcontextprotocol/inspectorcan also be helpful (npm run inspector).
(Remember to stop this manually run server before relying on the MCP Host to start it via the settings file.)
Architecture & Flow
- MCP Host Request: An LLM asks the MCP Host (e.g., VS Code Extension) to call the
isolatorserver'sexecute_codetool with arguments. - Server Processing (
index.ts):- Receives the
tools/callrequest via stdio. - Validates arguments using Zod.
- Loads configuration from
isolator_config.json. - Determines the code source:
- If
snippet_nameis provided, reads the corresponding file from the configuredpromptsDirand determines the language from the file extension. - If
entrypoint_codeandlanguageare provided, uses them directly.
- If
- Creates a temporary directory on the host.
- Writes the entrypoint code and any
additional_filesinto the temporary directory. - Constructs the command-line arguments for the embedded
isolatorGo CLI, including security flags from the config and the path to the temporary directory. - Spawns the
isolatorprocess using Node.jschild_process.spawn.
- Receives the
- Go CLI Execution (
isolator-cli/isolator run):- Parses flags (including the new
--envflag). - Creates a tar stream of the temporary directory contents.
- Uses the Docker SDK to create a container with specified image, resource limits, environment variables (from
--env), and security settings (NO bind mount). - Uses
CopyToContainerto copy the tar stream into the container's working directory. - Starts the container, which executes the requested command (e.g.,
python /workspace/hello_world.py). - Waits for completion, captures stdout/stderr.
- Removes the container.
- Prints the result (status, output, etc.) as JSON to its stdout.
- Parses flags (including the new
- Server Result Handling (
index.ts):- Reads the JSON output from the finished
isolatorprocess stdout. - Parses the JSON result.
- Formats the
CallToolResultfor MCP, combining stdout/stderr and settingisErrorif the Go CLI reported a non-success status. - Sends the result back to the MCP Host.
- Cleans up the temporary directory on the host.
- Reads the JSON output from the finished
- MCP Host Response: Relays the result back to the LLM, which then formulates a response for the user.
execute_code Tool
Description
Executes code (Python, Go, JavaScript) in a secure, isolated container environment.
Input Schema (arguments)
language(string, optional): The programming language (e.g., "python", "go", "javascript"). Required ifsnippet_nameis not provided.entrypoint_code(string, optional): The main code content to execute. Required ifsnippet_nameis not provided.entrypoint_filename(string, optional): Filename for the main code (e.g., "main.py", "script.js"). Defaults based on language if not provided.additional_files(array, optional): Array of objects, each with:filename(string, required): Name of the additional file.content(string, required): Content of the additional file.
snippet_name(string, optional): Name of a pre-defined code snippet file (without extension) located in the configuredpromptsDir. Mutually exclusive withlanguageandentrypoint_code.
Constraint: Either snippet_name OR both language and entrypoint_code must be provided.
Output (CallToolResult)
content: An array containing a singleTextContentobject.type: "text"text: A string containing the combined stdout and stderr from the execution, formatted like:
If an error occurred during execution (non-zero exit code, timeout), the text will be prepended with--- stdout --- [Actual stdout output] --- stderr --- [Actual stderr output]Execution Failed (status): [error message]\n\n.
isError(boolean):trueif the execution status reported by theisolatorCLI was "error" or "timeout",falseotherwise.
(Protocol-level errors, like invalid arguments or failure to start the process, will result in a standard MCP error response instead of a CallToolResult).