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
Claude Desktop Integration
Cursor Integration
- Manual Setup
MCP Tools
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:

Start AgentExecMCP:
```
make quick-start
```
Install Claude Desktop configuration:
```
make install-claude-config
```
Restart Claude Desktop and look for the MCP tools icon! 🎉

Manual Setup (if you prefer)

Start the SSE server:

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

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

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)

Start the SSE server:
```
make quick-start
```

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.

AgentExecMPC

README Documentation