Skip to main content
Glama
realugbun

AgentExecMPC

by realugbun
OverviewSchemaRelated ServersScoreDiscussions
Python
Hybrid

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: Sandbox MCP

📋 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:

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

🔧 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.

Available Tools

3 tools
execute_codeA
Execute code snippets in Python, Node.js, or Go with automatic environment setup.

This tool creates temporary files and executes code in isolated environments
with proper cleanup and timeout handling. Supports multiple programming
languages with their respective runtimes.

Supported Languages:
- Python: Full Python 3.x environment with standard library
- Node.js/JavaScript: Node.js runtime with npm packages
- Go: Go compiler and runtime environment with CGO_ENABLED=0

Features:
- Automatic temporary file management
- Language-specific execution environments
- Configurable timeout controls
- Detailed execution feedback
- Secure code isolation
- Temporary files are deleted after execution; code is non-persistent. Use the shell tool to create reusable scripts.

Args:
    request: Code execution parameters including code, language, and timeout

Returns:
    ExecutionResponse: Complete execution results with output, errors,
                      performance metrics, and success status

Examples:
- Python: {"code": "print('Hello World')", "language": "python"}
- Node.js: {"code": "console.log('Hello World')", "language": "node"}
- Go: {"code": "package main\nfunc main() { println("Hello") }", "language": "go"}
ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fully discloses behavioral traits: temporary files, isolated environments, proper cleanup, timeout handling, non-persistent code, and secure isolation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections, bullet points, and examples. Every sentence adds value, and the main action is front-loaded. No redundant text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (multiple languages, timeout, isolation), the description covers all key aspects: supported languages, features, execution details, and return type. No output schema, but the description explains the response structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The single parameter 'request' is a nested object with its properties described in the schema. The description adds value by listing the included parameters (code, language, timeout), providing examples, and explaining features, but does not add significant meaning beyond the schema's subfield descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool executes code snippets in Python, Node.js, or Go with automatic environment setup. It lists supported languages and features, and distinguishes from sibling tool 'shell' by stating to use shell for reusable scripts.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit guidance on when to use (execute code snippets) and when not to (not for persistent scripts), with alternatives mentioned ('Use the shell tool to create reusable scripts'). It includes examples for each language.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

install_packageA
Install packages using pip, npm, or Go modules with version control.

This tool provides a unified interface for package installation across
different programming environments. Supports version pinning and provides
detailed installation feedback with proper error handling.

Supported Package Managers:
- pip: Python package installer (PyPI packages)
- npm: Node.js package manager (npm registry)
- go: Go module system (Go packages)

Features:
- Version pinning support
- Installation progress tracking
- Dependency resolution
- Extended timeout for large packages
- Comprehensive error reporting

Args:
    request: Package installation parameters including name, manager, and version

Returns:
    ExecutionResponse: Installation results with output, any errors,
                      and installation success status

Examples:
- Install Python package: {"package": "requests", "package_manager": "pip"}
- Install with version: {"package": "lodash", "package_manager": "npm", "version": "4.17.21"}
- Install Go module: {"package": "github.com/gin-gonic/gin", "package_manager": "go"}
ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations were provided, so the description must disclose behavioral traits. It mentions version pinning, progress tracking, dependency resolution, extended timeout, and error reporting. This provides good insight, though it does not explicitly state if the operation is safe or destructive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections and examples, but it is somewhat verbose. The key information is front-loaded, though some repetition could be trimmed.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity and good schema descriptions, the description is mostly complete. It mentions the return type ExecutionResponse, which compensates for the lack of an output schema. However, it could include more detail on error handling or preconditions.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Parameter descriptions in the schema are detailed, so schema coverage is high (100%). The tool description adds value by summarizing version pinning and providing examples beyond the schema, earning a 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it installs packages using pip, npm, or Go modules with version control. The verb 'install' and resource 'packages' are specific and distinguish it from siblings execute_code and shell.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use the tool (package installation across environments) but lacks explicit exclusions or alternatives. Knowledge of siblings suggests alternative tools for code execution or shell commands.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

shellA
Execute shell commands in a secure sandboxed environment.

This tool allows executing arbitrary shell commands with built-in safety controls
including timeout limits, working directory restrictions, and process cleanup.
Perfect for file operations, system commands, and shell scripting tasks.

Features:
- Configurable timeout (default: 60s, max: 300s)
- Custom working directory support
- Automatic process cleanup
- Sandboxed execution in workspace
- Comprehensive error handling

Args:
    request: Shell execution parameters including command, timeout, and working directory

Returns:
    ExecutionResponse: Complete execution results with stdout, stderr, exit code,
                      duration, and success status

Examples:
- List files: {"command": "ls -la"}
- Create directory: {"command": "mkdir -p /workspace/new_folder"}
- Run with timeout: {"command": "long_running_task", "timeout": 120}
- Custom directory: {"command": "pwd", "cwd": "/workspace/subfolder"}
ParametersJSON Schema
NameRequiredDescriptionDefault
requestYes

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses key traits: sandboxed execution, configurable timeout (60s default, 300s max), working directory support, automatic cleanup, and error handling. However, it omits details like network access restrictions or persistency of file changes.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with sections (intro, features, args, returns, examples) and uses bullet points. It front-loads the purpose. However, it is somewhat verbose; e.g., 'sandboxed execution' appears twice and some feature points could be merged.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, the description explains returns (stdout, stderr, exit code, duration, success status). It covers timeout, working directory, error handling, and command constraints (64KB limit from schema, but not in description). It lacks mention of input size limit and does not detail sandbox restrictions, but overall is fairly complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0% for the top-level parameter 'request', so the description must compensate. It lists 'command, timeout, and working directory' in Args and provides examples, but does not explain each parameter's semantics beyond what the schema already provides. The examples add value, but not enough to fully compensate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Execute shell commands in a secure sandboxed environment' with specific verb-resource. It distinguishes from sibling tools 'execute_code' and 'install_package' by focusing on arbitrary shell commands for file operations, system commands, and scripting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context: 'Perfect for file operations, system commands, and shell scripting tasks.' It implicitly differentiates from siblings but does not explicitly state when not to use or provide alternative suggestions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedexecute_code
    • First observedinstall_package
    • First observedshell
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool targets a distinct function: executing code, installing packages, and running shell commands. There is no overlap in their purposes.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (execute_code, install_package, shell). 'Shell' is a noun but functions as a clear command name.

Tool Count5/5

With only 3 tools, the server is tightly scoped for code execution and environment management. Each tool serves a necessary role without clutter.

Completeness4/5

The set covers core operations: running code, installing packages, and shell access. A minor gap is the lack of package uninstallation or listing, but the essential workflows are present.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • Sandbox MCP

    pottekkat
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol (MCP) server that enables LLMs to run ANY code safely in isolated Docker containers.
    121
    MIT

  • MCP Shell Server

    mako10k
    A
    license
    B
    quality
    A
    maintenance
    A secure MCP server for shell operations, terminal management, and process control, enabling AI assistants to safely execute commands and manage interactive sessions.
    13
    204
    6
    MIT

  • CodeBox-AI

    tomconte
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server for secure, session-based Python code execution in Docker containers, enabling LLM applications to run code, manage state, and access files.
    9
    MIT

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/realugbun/AgentExecMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server