MCP Code Executor

Features

• Execute Python code from LLM prompts
• Support for incremental code generation to overcome token limitations
• Run code within a specified environment (Conda, virtualenv, or UV virtualenv)
• Install dependencies when needed
• Check if packages are already installed
• Dynamically configure the environment at runtime
• Configurable code storage directory

Prerequisites

• Node.js installed
• One of the following:
• Conda installed with desired Conda environment created
• Python virtualenv
• UV virtualenv

Setup

1. Clone this repository:

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

2. Navigate to the project directory:

   cd mcp_code_executor
   

3. Install the Node.js dependencies:

   npm install
   

4. Build the project:

   npm run build
   

Configuration

To configure the MCP Code Executor server, add the following to your MCP servers configuration file:

Using Node.js

{
  "mcpServers": {
    "mcp-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"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "mcp-code-executor": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-code-executor"
      ]
    }
  }
}

Note: The Dockerfile has been tested with the venv-uv environment type only. Other environment types may require additional configuration.

Environment Variables## Required Variables

• CODE_STORAGE_DIR: Directory where the generated code will be stored

Environment Type (choose one setup)

• For Conda:
• ENV_TYPE: Set to conda
• CONDA_ENV_NAME: Name of the Conda environment to use
• For Standard Virtualenv:
• ENV_TYPE: Set to venv
• VENV_PATH: Path to the virtualenv directory
• For UV Virtualenv:
• ENV_TYPE: Set to venv-uv
• UV_VENV_PATH: Path to the UV virtualenv directory

Available Tools

The MCP Code Executor provides the following tools to LLMs:

1. execute_code
2. install_dependencies
3. check_installed_packages
4. configure_environment
5. get_environment_config
6. initialize_code_file
7. append_to_code_file
8. execute_code_file
9. read_code_file

Usage

Once configured, the MCP Code Executor will allow LLMs to execute Python code by generating a file in the specified CODE_STORAGE_DIR and running it within the configured environment. LLMs can generate and execute code by referencing this MCP server in their prompts.

Handling Large Code Blocks

For larger code blocks that might exceed LLM token limits, use the incremental code generation approach:

1. Initialize a file with the basic structure using initialize_code_file
2. Add more code in subsequent calls using append_to_code_file
3. Verify the file content if needed using read_code_file
4. Execute the complete code using execute_code_file

This approach allows LLMs to write complex, multi-part code without running into token limitations.

Backward Compatibility

This package maintains backward compatibility with earlier versions. Users of previous versions who only specified a Conda environment will continue to work without any changes to their configuration.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.