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