Overview

This MCP (Model Context Protocol) server lets language models and developer tools execute Python code inside a specific Conda environment. Instead of running code in the LLM process or in a global interpreter, the server launches code in a chosen Conda environment and returns structured outputs (stdout, stderr, exit code, files). That makes it easier to test, reproduce, and validate Python snippets in the exact environment they will run in.

The server is designed for integration with LLM tooling via MCP-compatible endpoints. Typical consumers are LLMs that need to execute or test generated Python, automated testing services, or developer tooling that must run code safely and reproducibly inside a Conda-managed environment.

Features

Execute arbitrary Python code inside a selected Conda environment
Capture stdout, stderr, exit code and attach generated files
Timeouts and resource limits to bound execution time
Optional package installation or preconfigured environments for reproducibility
Simple HTTP/JSON interface for integration with LLMs and MCP clients
Designed to be run in a sandboxed host (Docker/cgroups) for additional process isolation

Installation / Configuration

Clone the repository and install the server requirements. Adjust commands to your environment.

Clone the repo:

git clone https://github.com/bazinga012/mcp_code_executor.git
cd mcp_code_executor

Option A — Install into a virtualenv for the server itself:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Option B — Use Docker (recommended for isolation):

docker build -t mcp-code-executor .
docker run --rm -p 8080:8080 \
  -v /path/to/conda/env:/opt/conda/envs/target_env:ro \
  -e CONDA_ENV_NAME=target_env \
  mcp-code-executor

Start the server (example CLI):

# example: point to a Conda environment prefix or environment name
python -m mcp_code_executor.server --port 8080 --conda-prefix /opt/conda/envs/target_env --timeout 30

Common configuration options

port: HTTP port to listen on (default: 8080)
conda-prefix / conda-env: path or name of the Conda environment to use
timeout: per-execution timeout in seconds
allowed-hosts / network: networking policy for executed processes

(Refer to the repository’s configuration file for exact option names and full list.)

Available Tools / Resources

The server exposes a small set of RPC-style endpoints designed for MCP/LLM integration. Typical endpoints include:

Endpoint	Method	Description
/execute	POST	Run Python code. Request includes code, env, timeout, and optional files.
/list-envs	GET	Return available Conda environments (if enabled).
/install	POST	(Optional) Install packages into the target environment (admin-only).
/health	GET	Health check for orchestration and readiness probes.

Example execute request (HTTP JSON):

POST /execute
Content-Type: application/json

{
  "env": "target_env",
  "code": "import sys\nprint('hello from', sys.executable)",
  "timeout": 10,
  "files": {}
}

Example execute response:

{
  "stdout": "hello from /opt/conda/envs/target_env/bin/python\n",
  "stderr": "",
  "exit_code": 0,
  "artifacts": []
}

Use Cases

LLM-assisted code generation and testing: Validate snippets in the same environment where they will be deployed (packages, Python version, OS-level dependencies).
Interactive education and notebooks: Run student-submitted code securely without giving direct shell access to the host.
CI debugging: Execute reproduction scripts using a known Conda environment to duplicate a failing CI job.
Package development: Run unit tests or snippets against multiple Conda environments to ensure compatibility.

Concrete example — run a unit test:

Upload your test file (or include via the “files” field).
POST to /execute with code that runs pytest on the uploaded file.
The server returns stdout/stderr and exit code so the LLM or CI system can interpret results.

Quick Example (curl)

Run a short script and get the output:

curl -sS -X POST http://localhost:8080/execute \
  -H "Content-Type: application/json" \
  -d '{"env":"target_env","code":"print(2+2)","timeout":5}'

Possible response:

{"stdout":"4\n","stderr":"","exit_code":0,"artifacts":[]}

Security & Best Practices

Run the server inside a container or VM and restrict network access to only trusted clients.
Use OS-level controls (cgroups, namespaces) to limit CPU, memory and filesystem visibility.
Enforce per-execution timeouts and execution user isolation to reduce abuse risk.
Avoid allowing arbitrary package installation in production without strict controls.
Log executions and audit usage to detect misuse.

Code Executor MCP Server for Conda Python