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 containersdocker>=7.1.0: Docker API clientfastmcp>=2.10.5: MCP server frameworkpydantic>=2.11.7: Data validationdotenv>=0.9.9: Environment variable managementtenacity>=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.