AgentExecMCP

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
• Cursor Integration
  • Manual Setup
• 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

AgentExecMCP 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

AgentExecMCP 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 AgentExecMCP:

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 AgentExecMCP-claude -p 8000:8000 -e MCP_TRANSPORT=sse AgentExecMCP

2. Configure Claude Desktop:

Open your Claude Desktop configuration file:

Add the following configuration:

{
     "mcpServers": {
       "AgentExecMCP": {
         "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 AgentExecMCP container
• Claude Desktop latest version

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

🖥️ Cursor Integration

AgentExecMCP works seamlessly with the Cursor IDE using the same SSE transport and configuration as Claude Desktop.

Manual Setup (for Cursor)

1. Start the SSE server:

make quick-start

2. Configure Cursor:

Open your Cursor mcp configuration file (for example `~/.cursor/mcp.json`) and add the following:

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

🔧 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 AgentExecMCP") 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.