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
- 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" ] } } } - macOS:
-
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
agentuser (UID 10001) - Sandboxed workspace: All operations in
/workspacedirectory - 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.