Agentexecmcp

🚀 AgentExecMCP

AgentExecMCP is a FastMCP server that offers core execution capabilities for AI agents. It is packaged in Docker, ensuring secure and effortless deployment.

🚀 Quick Start

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

✨ 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

📦 Installation

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

💻 Usage Examples

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:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json 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"
         ]
       }
     }
   }
   

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())

🔧 Technical Details

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"
      }
    }
  }
}

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

📚 Documentation

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.