Isolator Mcp

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](./isolator-cli), 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_code MCP 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 isolator Go 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 isolator CLI).
• Returns structured results (stdout, stderr, status) via MCP, setting isError: true on 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-cli Go binary.
• Node.js and npm: Required to install dependencies, build, and run the isolator-mcp TypeScript server.

Installation

1. Build isolator Go CLI: Navigate to the embedded Go CLI directory and build the binary:

``bash cd isolator-cli go build -o isolator main.go cd .. ` This creates the ./isolator-cli/isolator` executable needed by the server.

1. Configure isolator-mcp:

• Edit isolator_config.json: Update isolatorPath to 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 the promptsDir (used for snippets) location if needed.
• Ensure the prompts directory exists (default: ./prompts). Add code snippet files (e.g., hello_world.py). The filename base (e.g., hello_world) is used as the snippet_name.

1. Install Server Dependencies: Navigate to the main directory (isolator-mcp) and run:

``bash npm install ``

1. Build Server: Compile the TypeScript code:

``bash npm run build ` This creates the executable script at build/index.js`.

1. Configure MCP Host: Add the server to your MCP client's settings file (e.g., cline_mcp_settings.json for the VS Code extension):

``json { "mcpServers": { "isolator": { "command": "node", "args": ["/Users/ompragash/Documents/Cline/MCP/isolator-mcp/build/index.js"], "env": {}, "disabled": false, "autoApprove": [] } } } ` *(Adjust the path in args` if 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 . 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):

1. Build Go CLI: Ensure the isolator Go CLI is built within its subdirectory:

``bash cd isolator-cli go build -o isolator main.go cd .. ``

1. Build TS Server: In this main directory (isolator-mcp), run npm install and npm run build.
2. Configure: Make sure isolator_config.json correctly points to the built ./isolator-cli/isolator binary via the isolatorPath key (use the absolute path).
3. Run Server: Execute the built server directly using Node:

``bash node build/index.js ` The server will start, connect via stdio, and print logs (including console.error messages from index.ts`) to the console.

1. 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/inspector can 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

1. MCP Host Request: An LLM asks the MCP Host (e.g., VS Code Extension) to call the isolator server's execute_code tool with arguments.
2. Server Processing (index.ts):

• Receives the tools/call request via stdio.
• Validates arguments using Zod.
• Loads configuration from isolator_config.json.
• Determines the code source:
• If snippet_name is provided, reads the corresponding file from the configured promptsDir and determines the language from the file extension.
• If entrypoint_code and language are provided, uses them directly.
• Creates a temporary directory on the host.
• Writes the entrypoint code and any additional_files into the temporary directory.
• Constructs the command-line arguments for the embedded isolator Go CLI, including security flags from the config and the path to the temporary directory.
• Spawns the isolator process using Node.js child_process.spawn.

1. Go CLI Execution (isolator-cli/isolator run):

• Parses flags (including the new --env flag).
• 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 CopyToContainer to 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.

1. Server Result Handling (index.ts):

• Reads the JSON output from the finished isolator process stdout.
• Parses the JSON result.
• Formats the CallToolResult for MCP, combining stdout/stderr and setting isError if the Go CLI reported a non-success status.
• Sends the result back to the MCP Host.
• Cleans up the temporary directory on the host.

1. 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 if snippet_name is not provided.
• entrypoint_code (string, optional): The main code content to execute. Required if snippet_name is 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 configured promptsDir. Mutually exclusive with language and entrypoint_code.

Constraint: Either snippet_name OR both language and entrypoint_code must be provided.

Output (CallToolResult)

• content: An array containing a single TextContent object.
• type: "text"
• text: A string containing the combined stdout and stderr from the execution, formatted like:

`` --- stdout --- [Actual stdout output] --- stderr --- [Actual stderr output] ` If an error occurred *during* execution (non-zero exit code, timeout), the text will be prepended with Execution Failed (status): [error message]\n\n`.

• isError (boolean): true if the execution status reported by the isolator CLI was "error" or "timeout", false otherwise.

(Protocol-level errors, like invalid arguments or failure to start the process, will result in a standard MCP error response instead of a CallToolResult).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Ompragash
• Source: Ompragash/isolator-mcp
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.