Mcp Code Executor

Mcp Code Executor

What is Mcp Code Executor about?

Mcp Code Executor provides an MCP server that lets large language models run Python snippets or full scripts inside a user‑defined Python environment (Conda, standard virtualenv, or UV virtualenv). It handles dependency installation, environment checks, and incremental file building to bypass token limits.

How to use Mcp Code Executor?

1. Install the Node.js project (or run it via npx).
2. Configure the server in the MCP configuration file, specifying the command, arguments, and required environment variables (CODE_STORAGE_DIR, ENV_TYPE, and the env‑specific variable such as CONDA_ENV_NAME).
3. From an LLM prompt, call the provided tools (execute_code, initialize_code_file, append_to_code_file, etc.) to generate, modify, and run code.
4. Retrieve results returned by the server.

Key features of Mcp Code Executor

• Execute arbitrary Python code or complete files.
• Incremental code generation (initialize_code_file, append_to_code_file, read_code_file) for large scripts.
• Automatic dependency installation (install_dependencies).
• Check installed packages before running code.
• Dynamic environment configuration at runtime (configure_environment).
• Supports Conda, standard virtualenv, and UV virtualenv.
• Configurable code storage directory.

Use cases of Mcp Code Executor

• Data analysis pipelines where an LLM builds and runs pandas/numpy code on the fly.
• Prototyping machine‑learning experiments with on‑demand library installation.
• Educational tools that let a model demonstrate code execution step‑by‑step.
• Automated testing or CI scripts generated by LLMs within isolated environments.

FAQ from the Mcp Code Executor

• Do I need to build the project before using it? Yes, run npm install and npm run build if you run it locally with Node. When using npx, the build step is handled by the published package.
• Can I change the Python environment after the server starts? Yes, use the configure_environment tool to switch ENV_TYPE and the corresponding environment identifier.
• What happens if a required package is missing? Call install_dependencies first; the server will install the packages into the configured environment.
• Is there a limit on code size? Large blocks should be split using the incremental file tools to avoid token limits.
• How is the code stored? Files are written under the directory defined by CODE_STORAGE_DIR; each file gets a unique identifier to avoid collisions.

MCP Code Executor

The MCP Code Executor is an MCP server that allows LLMs to execute Python code within a specified Python environment. This enables LLMs to run code with access to libraries and dependencies defined in the environment. It also supports incremental code generation for handling large code blocks that may exceed token limits.

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

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

{
  "name": "execute_code",
  "arguments": {
    "code": "import numpy as np\nprint(np.random.rand(3,3))",
    "filename": "matrix_gen"
  }
}

2. install_dependencies

Installs Python packages in the environment.

{
  "name": "install_dependencies",
  "arguments": {
    "packages": ["numpy", "pandas", "matplotlib"]
  }
}

3. check_installed_packages

Checks if packages are already installed in the environment.

{
  "name": "check_installed_packages",
  "arguments": {
    "packages": ["numpy", "pandas", "non_existent_package"]
  }
}

4. configure_environment

Dynamically changes the environment configuration.

{
  "name": "configure_environment",
  "arguments": {
    "type": "conda",
    "conda_name": "new_env_name"
  }
}

5. get_environment_config

Gets the current environment configuration.

{
  "name": "get_environment_config",
  "arguments": {}
}

6. initialize_code_file

Creates a new Python file with initial content. Use this as the first step for longer code that may exceed token limits.

{
  "name": "initialize_code_file",
  "arguments": {
    "content": "def main():\n    print('Hello, world!')\n\nif __name__ == '__main__':\n    main()",
    "filename": "my_script"
  }
}

7. append_to_code_file

Appends content to an existing Python code file. Use this to add more code to a file created with initialize_code_file.

{
  "name": "append_to_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py",
    "content": "\ndef another_function():\n    print('This was appended to the file')\n"
  }
}

8. execute_code_file

Executes an existing Python file. Use this as the final step after building up code with initialize_code_file and append_to_code_file.

{
  "name": "execute_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py"
  }
}

9. read_code_file

Reads the content of an existing Python code file. Use this to verify the current state of a file before appending more content or executing it.

{
  "name": "read_code_file",
  "arguments": {
    "file_path": "/path/to/code/storage/my_script_abc123.py"
  }
}

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.

License

This project is licensed under the MIT License.