Skip to main content
Glama
philschmid

Code Sandbox MCP Server

by philschmid
OverviewSchemaRelated ServersScoreDiscussions
Python

Code Sandbox MCP Server

The Code Sandbox MCP Server is a lightweight, STDIO-based Model Context Protocol (MCP) Server, allowing AI assistants and LLM applications to safely execute code snippets using containerized environments. It is uses the llm-sandbox package to execute the code snippets.

Code Sandbox MCP

How It Works:

  1. Starts a container session (podman, docker, etc.) and ensures the session is open.

  2. Writes the code to a temporary file on the host.

  3. Copies this temporary file into the container at the configured workdir.

  4. Executes the language-specific commands to run the code, e.g. python python3 -u code.py or javascript node -u code.js

  5. Captures the output and error streams from the container.

  6. Returns the output and error streams to the client.

  7. Stops and removes the container.

Available Tools:

  • run_python_code - Executes a snippet of Python code in a secure, isolated sandbox.

    • code (string, required): The Python code to execute.

  • run_js_code - Executes a snippet of JavaScript (Node.js) code in a secure, isolated sandbox.

    • code (string, required): The JavaScript code to execute.

Installation

pip install git+https://github.com/philschmid/code-sandbox-mcp.git

Related MCP server: Container-MCP

Getting Started: Usage with an MCP Client

Examples:

To use the Code Sandbox MCP server, you need to add it to your MCP client's configuration file (e.g., in your AI assistant's settings). The server is designed to be launched on-demand by the client.

Add the following to your mcpServers configuration:

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
    }
  }
}

Provide Secrets and pass through environment variables

You can pass through environment variables to the sandbox by setting the --pass-through-env flag when starting the MCP server and providing the env when starting the server

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
      "args": ["--pass-through-env", "API_KEY,SECRET_TOKEN"]
      "env": {
        "API_KEY": "1234567890",
        "SECRET_TOKEN": "1234567890"
      }
    }
  }
}

Provide a custom container image

You can provide a custom container image by setting the CONTAINER_IMAGE and CONTAINER_LANGUAGE environment variables when starting the MCP server. Both variables are required as the CONTAINER_LANGUAGE is used to determine the commands to run in the container and the CONTAINER_IMAGE is used to determine the image to use.

Note: When providing a custom container image both tools will use the same container image.

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
      "env": {
        "CONTAINER_IMAGE": "your-own-image",
        "CONTAINER_LANGUAGE": "python" # or "javascript"
      }
    }
  }
}

Use with Gemini SDK

The code-sandbox-mcp server can be used with the Gemini SDK by passing the tools parameter to the generate_content method.

from fastmcp import Client
from google import genai
import asyncio


mcp_client = Client(
    {
        "local_server": {
            "transport": "stdio",
            "command": "code-sandbox-mcp",
        }
    }
)
gemini_client = genai.Client()


async def main():
    async with mcp_client:
        response = await gemini_client.aio.models.generate_content(
            model="gemini-2.5-flash",
            contents="Use Python to ping the google.com website and return the response time.",
            config=genai.types.GenerateContentConfig(
                temperature=0,
                tools=[mcp_client.session],  # Pass the FastMCP client session
            ),
        )
        print(response.text)

if __name__ == "__main__":
    asyncio.run(main())

Use with Gemini CLI

The code-sandbox-mcp server can be used with the Gemini CLI. You can configure MCP servers at the global level in the ~/.gemini/settings.json file or in your project's root directory, create or open the .gemini/settings.json file. Within the file, add the mcpServers configuration block.

Gemini CLI Settings

See settings.json for an example and read more about the Gemini CLI

{
  "mcpServers": {
    "code-sandbox": {
      "command": "code-sandbox-mcp",
    }
  }
}

Customize/Build new Container Images

The repository comes with 2 container images, which are published on Docker Hub:

  • philschmi/code-sandbox-python:latest

  • philschmi/code-sandbox-js:latest

docker build -t philschmi/code-sandbox-python:latest -f containers/Dockerfile.python .
docker build -t philschmi/code-sandbox-js:latest -f containers/Dockerfile.nodejs .

The script will build the image using the current user's account. To update the images you want to use you can either pass the --python-image or --js-image flags when starting the MCP server or update the const.py file.

To push the images to Docker Hub you need to retag the images to your own account and push them.

docker tag philschmi/code-sandbox-python:latest <your-account>/code-sandbox-python:latest
docker push <your-account>/code-sandbox-python:latest

To customize or install additional dependencies you can add them to the Dockerfile and build the image again.

Testing

With MCP Inspector

Start the server with streamable-http and test your server using the MCP inspector. Alternatively start inspector and run the server with stdio.

npx @modelcontextprotocol/inspector

To run the test suite for code-sandbox-mcp and its components, clone the repository and run:

# You may need to install development dependencies first
pip install -e ".[dev]"

# Run the tests
pytest tests/

License

Code Sandbox MCP Server is open source software licensed under the MIT License.

Available Tools

2 tools
run_javascript_codeB

Execute JavaScript code in the sandbox environment and captures the standard output and error.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesThe JavaScript code to execute, included libraries are @google/genai

Output Schema

ParametersJSON Schema
NameRequiredDescription
textYes
typeYes
_metaNo
annotationsNo

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the sandbox environment and capture of output/error, but lacks details on execution limits, security implications, error handling, or what the sandbox entails. For a code execution tool with zero annotation coverage, this is insufficient behavioral disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no wasted words. It front-loads the core action and key details, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (code execution), lack of annotations, and presence of an output schema, the description is minimally adequate. It covers the basic purpose and output capture but misses critical behavioral aspects like safety, limits, and comparison to siblings. The output schema likely handles return values, reducing the burden here.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents the 'code' parameter fully. The description adds that included libraries are '@google/genai', which provides some context beyond the schema, but doesn't elaborate on syntax, supported features, or other libraries. Baseline 3 is appropriate as the schema does most of the work.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Execute JavaScript code') and the environment ('in the sandbox environment'), and specifies what it captures ('standard output and error'). It distinguishes from the sibling 'run_python_code' by specifying JavaScript, but doesn't explicitly contrast them. The purpose is specific and actionable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives like 'run_python_code', nor does it mention any prerequisites, constraints, or typical use cases. It simply states what the tool does without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_python_codeB

Execute Python code in the sandbox environment and captures the standard output and error.

ParametersJSON Schema
NameRequiredDescriptionDefault
codeYesThe Python code to execute, included libraries are numpy, pandas, matplotlib, scikit-learn, requests, google-genai

Output Schema

ParametersJSON Schema
NameRequiredDescription
textYes
typeYes
_metaNo
annotationsNo

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It discloses key behavioral traits: execution in a 'sandbox environment' (implying isolation/safety) and capture of 'standard output and error'. However, it lacks details on execution limits, timeouts, memory constraints, security implications, or response format beyond capture. The description adds value but is incomplete for a code execution tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It is front-loaded with the core action and environment, making it easy to parse. Every word earns its place without redundancy or fluff.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (code execution), no annotations, and an output schema present (which covers return values), the description is reasonably complete. It specifies the sandbox environment and capture behavior, which are critical for understanding. However, it lacks details on execution constraints and security, leaving some gaps for a potentially risky operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the parameter 'code' fully documented in the schema (including available libraries). The description adds no additional parameter semantics beyond what the schema provides, such as code length limits or syntax requirements. Baseline 3 is appropriate as the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: 'Execute Python code in the sandbox environment and captures the standard output and error.' It specifies the verb ('execute'), resource ('Python code'), and environment ('sandbox'), but doesn't explicitly differentiate from its sibling 'run_javascript_code' beyond the language name.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention the sibling tool 'run_javascript_code' or any other alternatives, nor does it specify prerequisites, constraints, or typical use cases. Usage is implied by the language name only.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 2 tool updates
    • First observedrun_javascript_code
    • First observedrun_python_code
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

The two tools are perfectly distinct, each targeting a different programming language (JavaScript vs Python) with identical functionality otherwise. There is no overlap or ambiguity in purpose, making tool selection straightforward for an agent.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern ('run_javascript_code' and 'run_python_code'), using the same verb 'run' and structured noun phrases. This predictability enhances readability and usability.

Tool Count2/5

With only two tools, the server feels under-scoped for a 'Code Sandbox' purpose, as it lacks support for other common languages (e.g., Java, C++, Ruby) or additional sandbox operations (e.g., managing files, setting timeouts). This minimal set limits functionality and may require agents to work around gaps.

Completeness2/5

The tool surface is severely incomplete for a code sandbox domain, covering only JavaScript and Python execution. Missing are tools for other languages, code analysis, input/output handling, or environment configuration, which are typical for such systems, leading to potential agent failures in broader tasks.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/philschmid/code-sandbox-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server