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

Related MCP server: MCP Docker Sandbox Interpreter

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.

Related Projects

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

MCP AgentRun Server

MCP AgentRun Server

Features

Installation

Prerequisites

Setup

Usage

From Cursor

Running the Server

Available Tools

Execute Python Code

Example Usage

Project Structure

Configuration

Testing

Dependencies

Development

Adding New Features

Running in Development Mode

License

Contributing

Related Projects

Resources

New MCP Servers

Latest Blog Posts

MCP directory API