README.md•4.35 kB
# MCP AgentRun Server
An MCP (Model Context Protocol) server that provides Python code execution capabilities using [AgentRun](https://github.com/agentrun-ai/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:
```bash
git clone <repository-url>
cd mcp-agentrun
```
2. Run the setup script:
```bash
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:
```json
{
"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
```bash
python src/server.py
```
### Available Tools
#### Execute Python Code
Execute Python code in a container:
```python
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:
```python
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:
```env
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
```bash
# 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](https://github.com/agentrun-ai/agentrun): Python code execution in containers
- [FastMCP](https://github.com/jlowin/fastmcp): Fast MCP server framework