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

1. Clone the repository:

git clone <repository-url>
cd mcp-agentrun

2. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. 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.

Related Projects

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