AgentExecMPC

<!-- Copyright 2025 AgentExecMPC Contributors

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. -->

A FastMCP server providing core execution capabilities for AI agents, packaged in Docker for secure and easy deployment.

⚡ Quick Start

Get up and running in 2 minutes: see QUICKSTART.md.

📋 Table of Contents

• Quick Start
• Features
• Make Commands
  • Quick Start Commands
  • Core Commands
  • Management Commands
  • Maintenance Commands
  • Example Workflow
• Claude Desktop Integration
  • Easy Setup with Make
  • Manual Setup
  • Test the Integration
  • Troubleshooting
• MCP Tools
  • Shell Tool
  • Execute Code Tool
  • Install Package Tool
• Client Connection Examples
• Security Features
• Environment
• MCP Protocol Support
• Development
• Testing
• Requirements
• Use Cases
• License

---

🚀 Features

• Shell Execution: Run bash commands with timeout and safety controls
• Multi-Language Code Execution: Python, Node.js, and Go support with optimized execution
• Package Management: Install packages via pip, npm, and go modules
• Multiple Transports: stdio and SSE
• Docker Deployment: Containerized for consistent execution environment
• MCP Protocol: Standards-compliant Model Context Protocol
• Safety Controls: Non-root execution, timeouts, concurrency limits
• Claude Desktop Integration: Works seamlessly with Claude Desktop via SSE transport
• Go Optimization: Go code execution with CGO_ENABLED=0 for improved compatibility

🛠️ Make Commands

AgentExecMPC includes a comprehensive Makefile that makes setup and management super easy. All commands are designed to be user-friendly for both technical and non-technical users.

Quick Start Commands

make help                # Show all available commands with descriptions
make quick-start         # Build and run with SSE transport (recommended)

Core Commands

make build              # Build the Docker container
make run                # Run with STDIO transport (interactive)
make run-sse            # Run with SSE transport (for Claude Desktop)

Management Commands

make status             # Show container status
make logs               # Show container logs (follows log output)
make health             # Check if server is responding
make stop               # Stop all running containers
make shell              # Open shell in running container

Development Commands

make lint               # Run ruff linter and formatter

Maintenance Commands

make test               # Test basic functionality
make clean              # Remove containers and images
make workspace          # Create workspace directory

Example Workflow

# First time setup
make quick-start                    # Builds and starts everything
make install-claude-config          # Sets up Claude Desktop

# Daily usage
make status                         # Check if running
make logs                          # View output
make stop                          # Stop when done

# Troubleshooting
make clean                         # Clean everything
make quick-start                   # Fresh start

🖥️ Claude Desktop Integration

AgentExecMPC works seamlessly with Claude Desktop using SSE transport. This is perfect for local development and testing.

Easy Setup with Make (Recommended)

Super simple 3-step setup:

1. Start AgentExecMPC:

   make quick-start
   

2. Install Claude Desktop configuration:

   make install-claude-config
   

3. Restart Claude Desktop and look for the MCP tools icon! 🎉

Manual Setup (if you prefer)

1. Start the SSE server:

   docker run -d --name agentexecmpc-claude -p 8000:8000 -e MCP_TRANSPORT=sse agentexecmpc
   

2. Configure Claude Desktop:

   Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   Add the following configuration:

   {
     "mcpServers": {
       "agentexecmpc": {
         "command": "npx",
         "args": [
           "mcp-remote",
           "http://localhost:8000/sse"
         ]
       }
     }
   }
   

3. Restart Claude Desktop and look for the MCP tools icon

Test the Integration

Try these commands in Claude Desktop:

• "Run a shell command to list files"
• "Execute some Python code to calculate 2+2"
• "Install the requests package using pip"

Troubleshooting

• Check server status: make status
• View logs: make logs
• Restart server: make stop && make quick-start

Prerequisites for Claude Desktop

• Node.js and npm installed on your system
• Docker running with the AgentExecMPC container
• Claude Desktop latest version

The mcp-remote package will be automatically installed by npx when first used.

🔧 MCP Tools

1. Shell Tool

Execute shell commands with safety controls.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "shell",
    "arguments": {
      "request": {
        "command": "echo 'Hello World!'",
        "timeout": 60,
        "cwd": "/workspace"
      }
    }
  }
}

2. Execute Code Tool

Run code snippets in Python, Node.js, or Go with optimized execution.

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "python",
        "code": "print('Hello from Python!')\nprint(2 + 2)",
        "timeout": 60
      }
    }
  }
}

Go Code Example:

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "execute_code",
    "arguments": {
      "request": {
        "language": "go",
        "code": "package main\nimport \"fmt\"\nfunc main() {\n    fmt.Println(\"Hello from Go!\")\n}",
        "timeout": 60
      }
    }
  }
}

Features:

• Python: Full Python 3.x environment with standard library
• Node.js: Node.js runtime with npm packages
• Go: Optimized execution with CGO_ENABLED=0 for better compatibility
• Automatic cleanup: Temporary files are created and cleaned up automatically
• Error handling: Compilation and runtime errors are properly captured

3. Install Package Tool

Install packages using various package managers.

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "install_package",
    "arguments": {
      "request": {
        "package_manager": "pip",
        "package": "requests",
        "version": "2.32.0"
      }
    }
  }
}

🌐 Client Connection Examples

FastMCP Client (Python)

from fastmcp import Client
import asyncio

async def main():
    # Connect via stdio to local container
    async with Client("docker run -i --rm agentexecmpc") as client:
        result = await client.call_tool("shell", {"request": {"command": "echo 'Hello!'"}})
        print(result[0].text)
    
    # Connect via SSE to HTTP server
    async with Client("http://localhost:8000/sse") as client:
        tools = await client.list_tools()
        print(f"Available tools: {[tool.name for tool in tools]}")

asyncio.run(main())

🔒 Security Features

• Non-root execution: Runs as agent user (UID 10001)
• Sandboxed workspace: All operations in /workspace directory
• Timeout controls: Configurable timeouts (default 60s, max 300s)
• Concurrency limits: Maximum 4 concurrent processes
• Input validation: Size limits and parameter validation
• Process cleanup: Automatic cleanup of running processes

🌍 Environment

The container includes:

• Ubuntu 22.04 base image
• Python 3.13.3 with pip package manager
• Node.js 20.19.2 with npm
• Go 1.23.4 with modules
• Development tools: git, curl, wget, build-essential
• Utilities: jq, ripgrep, fd-find, htop

📡 MCP Protocol Support

The server implements the Model Context Protocol (MCP) 2024-11-05 specification with multiple transport options:

• STDIO: Default transport for local tools and command-line usage
• SSE: Server-Sent Events transport for HTTP deployment and Claude Desktop

🛠️ Development

Local Development

# Install dependencies
uv sync

# Run server locally (stdio)
uv run python -m app.main

# Run server with SSE transport
MCP_TRANSPORT=sse uv run python -m app.main

Testing

The server has been tested with:

• ✅ MCP protocol compliance across all transports
• ✅ All three tools (shell, execute_code, install_package)
• ✅ Multi-language code execution with package imports
• ✅ Package installation and verification
• ✅ Docker container deployment
• ✅ Claude Desktop integration via SSE transport
• ✅ Safety and timeout controls

📋 Requirements

• Docker (for containerized deployment)
• Python 3.12+ (for local development)
• UV package manager (for dependency management)
• Node.js and npm (for Claude Desktop integration)

🎯 Use Cases

• Claude Desktop Integration: Provide execution capabilities directly in Claude Desktop
• AI Agent Execution: Provide safe execution environment for AI agents
• Code Sandboxing: Run untrusted code in isolated container
• Multi-language Development: Support Python, Node.js, and Go workflows
• Package Management: Install and test packages across ecosystems
• Shell Automation: Execute system commands with proper controls
• Kubernetes Deployment: Scale execution capabilities in cloud environments

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

This project follows the guiding principles of being fast to build, reproducible, safe by default, and extensible.