Code Executor

The MCP Code Executor lets you run Python code inside a controlled Python environment, enabling you to explore ideas, test snippets, and build larger programs incrementally without leaving the MCP workflow. It supports switching environments on the fly, installing dependencies as needed, and persisting generated code in a dedicated storage directory for reuse and iterative development.

How to use

You can use this MCP server from an MCP client by asking it to execute Python code in a configured environment. Start by ensuring your environment is set up (Conda, standard virtualenv, or UV virtualenv) and that the code storage directory is writable. Use the provided tools to initialize, extend, and run code files in small, incremental steps so you can handle large blocks without token limits.

How to install

Prerequisites you need installed on the host machine:

How to install

# Prerequisites
node -v
python --version
# Optional: Conda if you want a Conda environment
conda --version

# 1) Clone the MCP Code Executor repository
git clone https://github.com/bazinga012/mcp_code_executor.git

# 2) Navigate to the project directory
cd mcp_code_executor

# 3) Install Node.js dependencies
npm install

# 4) Build the project
npm run build

Configure the server and environment

Configure how the MCP Code Executor starts and which Python environment it uses. You can run it directly with Node.js or via Docker. The following options are shown for local Node-based execution and for running through Docker.

Configuration details

Environment variables you can set when starting the server are used to control storage and the Python environment. The key variables are:

Code storage and environments

• CODE_STORAGE_DIR: Directory where the generated code will be stored.
• ENV_TYPE: Type of environment to use. Choose one of:
• conda: Use a Conda environment; specify CONDA_ENV_NAME.
• venv: Use a standard virtualenv; specify VENV_PATH.
• venv-uv: Use a UV virtualenv; specify UV_VENV_PATH.

Running with Node.js (stdio)

Start the MCP Code Executor by invoking Node.js with the built entry point and the required environment variables.

Example startup configuration (stdio)

{
  "type": "stdio",
  "name": "code_executor",
  "command": "node",
  "args": ["/path/to/mcp_code_executor/build/index.js"],
  "env": {
    "CODE_STORAGE_DIR": "/path/to/code/storage",
    "ENV_TYPE": "conda",
    "CONDA_ENV_NAME": "your-conda-env"
  }
}

Running with Docker (stdio)

{
  "type": "stdio",
  "name": "code_executor_docker",
  "command": "docker",
  "args": [
    "run",
    "-i",
    "--rm",
    "mcp-code-executor"
  ]
}

Available tools and their purposes

The MCP Code Executor exposes a set of tools you can invoke from prompts to manage and run Python code in the configured environment.

1. execute_code

Executes Python code in the configured environment. Best for short code snippets.

2. install_dependencies

Installs Python packages in the environment.

3. check_installed_packages

Checks if packages are already installed in the environment.

4. configure_environment

Dynamically changes the environment configuration.

5. get_environment_config

Gets the current environment configuration.

6. initialize_code_file

Creates a new Python file with initial content to start multi-part code that may exceed token limits.

7. append_to_code_file

Appends content to an existing Python code file to build up code progressively.

8. execute_code_file

Executes an existing Python file as the final step after building up code pieces.

9. read_code_file

Reads the content of an existing Python code file to verify its current state.

Usage notes

Use the incremental code generation pattern to handle large scripts: initialize a file, append additional code in subsequent steps, and finally execute the complete file. Store generated code in CODE_STORAGE_DIR so you can reuse and continue work across prompts.

Backward compatibility and contribution

The package maintains backward compatibility with earlier environment setups. Contributions are welcome; consider opening issues or submitting pull requests for improvements.

License

This project is licensed under the MIT License.

Available tools

execute_code

Executes Python code in the configured environment. Best for short code snippets.

install_dependencies

Installs Python packages in the environment.

check_installed_packages

Checks if packages are already installed in the environment.

configure_environment

Dynamically changes the environment configuration.

get_environment_config

Gets the current environment configuration.

initialize_code_file

Creates a new Python file with initial content for long-running code blocks.

append_to_code_file

Appends content to an existing Python code file to extend code across steps.

execute_code_file

Executes an existing Python file as the final step.

read_code_file

Reads the content of an existing Python code file to verify state.