MCP AgentRun Server

An MCP (Model Context Protocol) server that provides Python code execution capabilities using AgentRun. This server can execute Python code in isolated Docker containers for safe and reproducible code execution.

Features

Safe Code Execution: Execute Python code in isolated Docker containers
Container Management: Automatic container lifecycle management with docker-compose
Environment Isolation: Each execution runs in a clean, isolated environment
Error Handling: Comprehensive error handling and logging
Easy Integration: Simple MCP interface for AI assistants and tools

Installation

Prerequisites

Python 3.13 or higher
Docker and Docker Compose
UV package manager (recommended)

Setup

Clone the repository:

git clone <repository-url>
cd mcp-agentrun

Run the setup script:

chmod +x setup.sh
./setup.sh

Usage

From Cursor

Go to Cursor Settings > Tools and Integrations > [New MCP Server] In the mcp.json file add the following:

{
  "mcpServers": {
    "python-code-executor": {
      "command": "/path/to/mcp-agentrun/.venv/bin/python",
      "args": [
        "/path/to/mcp-agentrun/src/server.py"
      ],
      "env": {
        "PYTHONPATH": "/path/to/mcp-agentrun",
        "AGENTRUN_API_DIR": "/path/to/mcp-agentrun/agentrun/agentrun-api",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Running the Server

python src/server.py

Available Tools

Execute Python Code

Execute Python code in a container:

result = execute_code(
    python_code="print('Hello, World!')\nprint(2 + 2)"
)

Returns the output of the code execution as a string.

Example Usage

See tests/test_build_container.py for a complete example:

import os
import subprocess
import dotenv
from agentrun import AgentRun

# Setup environment
rootdir = subprocess.run(["git", "rev-parse", "--show-toplevel"], 
                        capture_output=True, text=True).stdout.strip()
agentrun_api_dir = os.path.join(rootdir, "agentrun", "agentrun-api")

dotenv.load_dotenv(os.path.join(agentrun_api_dir, ".env.dev"))
container_name = os.getenv("CONTAINER_NAME")

# Execute code
with ComposeService(agentrun_api_dir):
    runner = AgentRun(container_name=container_name)
    code_from_llm = "print(1+2)"
    result = runner.execute_code_in_container(code_from_llm)
    print(result)  # Output: 3

Project Structure

mcp-agentrun/
├── agentrun/                 # AgentRun submodule
├── src/
│   ├── __init__.py
│   └── server.py            # MCP server implementation
├── tests/
│   ├── test_build_container.py  # Container testing
│   ├── test.py              # Unit tests
│   ├── test_integration.py  # Integration tests
│   └── dev.ipynb            # Development notebook
├── pyproject.toml           # Project configuration
├── pytest.ini              # Pytest configuration
├── run_tests.py             # Test runner script
├── setup.sh                 # Setup script
└── README.md               # This file

Configuration

The server requires a .env.dev file in the agentrun/agentrun-api/ directory with the following variables:

CONTAINER_NAME=your-container-name

Testing

Dependencies

agentrun>=0.2.5: Python code execution in containers
docker>=7.1.0: Docker API client
fastmcp>=2.10.5: MCP server framework
pydantic>=2.11.7: Data validation
dotenv>=0.9.9: Environment variable management
tenacity>=9.1.2: Retry logic

Development

Adding New Features

Fork the repository
Create a feature branch
Make your changes
Add tests
Submit a pull request

Running in Development Mode

# Install in development mode
uv pip install -e .

# Run the server
python src/server.py

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

AgentRun: Python code execution in containers
FastMCP: Fast MCP server framework

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables safe Python code execution in isolated Docker containers through the AgentRun framework. Provides automatic container lifecycle management and comprehensive error handling for secure and reproducible code execution.

Related MCP Servers

Python MCP Sandbox
JohanLi233
-
security
A
license
-
quality
An interactive Python code execution environment that allows users and LLMs to safely execute Python code and install packages in isolated Docker containers.
Last updated -
24
Apache 2.0
MCP Docker Sandbox Interpreter
svngoku
-
security
F
license
-
quality
A secure Docker-based environment that allows AI assistants to safely execute code without direct access to the host system by running all code within isolated containers.
Last updated -
2
MCP Sandbox
JohanLi233
-
security
A
license
-
quality
An interactive Python code execution tool that allows users and LLMs to safely execute Python code and install packages in isolated Docker containers.
Last updated -
24
Apache 2.0
MCP Executor Server
nikhilkumaragarwal-shyftlabs
-
security
F
license
-
quality
A secure server that enables code execution in isolated Docker environments, supporting Python with strict security constraints including network isolation, limited filesystem access, and resource limitations.
Last updated -

View all related MCP servers

MCP AgentRun Server