AgentExecMCP

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

Get up and running in 2 minutes: seeQUICKSTART.md.

- Quick Start
- Features
- Make Commands

- Quick Start Commands
- Core Commands
- Management Commands
- Maintenance Commands
- Example Workflow

- Easy Setup with Make
- Manual Setup
- Test the Integration
- Troubleshooting

- Shell Tool
- Execute Code Tool
- Install Package Tool

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

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

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

make lint # Run ruff linter and formatter

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

# 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

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

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

Restart Claude Desktopand look for the MCP tools icon

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

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

- Node.js and npminstalled on your system
- Dockerrunning with the AgentExecMCP container
- Claude Desktoplatest version

Themcp-remotepackage will be automatically installed by npx when first used.

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

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

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

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

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

- 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

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

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

- Non-root execution: Runs asagentuser (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

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

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

# 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

- ✅ 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

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

- 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

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

MCP security scanner — finds tool poisoning, credential leaks, and insecure transports in AI agent configurations.