Which integrations are available for this server?

Containerized deployment for secure execution environment, with configuration options for both STDIO and SSE transports

AgentExecMCP

License

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.

Related MCP server: Terminal MCP Server

📋 Table of Contents

🚀 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