Cluster Execution MCP Server
Enables routing and execution of hardware-related tasks on nodes equipped with Arduino connectivity and capabilities.
Automatically offloads and executes Docker container commands, builds, and management tasks across distributed cluster nodes.
Distributes Jest test suites across the cluster for parallel execution and improved testing throughput.
Provides distributed command execution and task routing specifically targeting x86_64 Linux nodes within the cluster.
Routes and executes commands across macOS-based nodes, supporting both Intel and ARM64 architectures for distributed tasks.
Automatically routes and executes Mocha-based test suites across optimal cluster nodes.
Offloads Node.js package management and build tasks to the most suitable nodes in the distributed network.
Routes LLM inference and model-serving workloads to dedicated inference nodes running Ollama.
Automatically routes pnpm build and installation commands to optimal nodes based on current cluster load.
Supports distributed execution of Podman container operations and builds across the node network.
Enables parallel and distributed execution of Python test suites via pytest across the agentic cluster.
Routes Swift compilation and build tasks to macOS nodes within the cluster.
Supports routing orchestration and coordination tasks to cluster nodes configured with Temporal.
Supports execution of commands and containerized workloads specifically targeting Ubuntu environments on Linux nodes.
Automatically offloads Yarn-based build processes and package management tasks to available cluster resources.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Cluster Execution MCP Server run my test suite in parallel across the cluster nodes"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Cluster Execution MCP Server
Cluster-aware command execution for distributed task routing across the AGI agentic cluster.
Version: 0.2.0
Features
Automatic task routing: Commands routed to optimal nodes based on load, capabilities, and requirements
Multi-node support: macpro51 (Linux x86_64), mac-studio (macOS ARM64), macbook-air (macOS ARM64), inference node
Dynamic IP resolution: mDNS, DNS, and fallback methods with caching
Security hardened: No shell injection, environment-based configuration, command validation
SSH connectivity verification: Retry logic with configurable timeouts
Parallel execution: Distribute commands across cluster for maximum throughput
Related MCP server: cli-executor-mcp
Installation
cd /mnt/agentic-system/mcp-servers/cluster-execution-mcp
pip install -e .
# For development:
pip install -e ".[dev]"Configuration
Claude Code Configuration
Add to ~/.claude.json:
{
"mcpServers": {
"cluster-execution": {
"command": "/mnt/agentic-system/.venv/bin/python3",
"args": ["-m", "cluster_execution_mcp.server"]
}
}
}Environment Variables
All configuration is externalized via environment variables:
Variable | Default | Description |
|
| SSH username for remote execution |
|
| SSH connection timeout (seconds) |
|
| Initial SSH connect timeout (seconds) |
|
| Number of SSH retry attempts |
|
| CPU usage % threshold for offloading |
|
| Load average threshold for offloading |
|
| Memory usage % threshold for offloading |
|
| Command execution timeout (seconds) |
|
| Status check timeout (seconds) |
|
| IP resolution cache TTL (seconds) |
|
| Gateway IP for route detection |
|
| DNS server for IP detection |
|
| Base path for databases |
Node Configuration
Node hostnames and IPs can be customized:
Variable | Default | Description |
|
| Mac Pro hostname |
|
| Mac Pro fallback IP |
|
| Mac Studio hostname |
|
| Mac Studio fallback IP |
|
| MacBook Air hostname |
|
| MacBook Air fallback IP |
|
| Inference node hostname |
|
| Inference node fallback IP |
MCP Tools
Tool | Description |
| Execute bash commands with automatic cluster routing |
| Get current cluster state and load distribution |
| Explicitly route command to specific node |
| Run multiple commands in parallel across nodes |
Usage Examples
Automatic Routing
# Heavy commands auto-route to least loaded node
result = await cluster_bash("make -j8 all")
# Simple commands run locally
result = await cluster_bash("ls -la")Force Specific Requirements
# Force Linux execution
result = await cluster_bash("docker build .", requires_os="linux")
# Force x86_64 architecture
result = await cluster_bash("cargo build", requires_arch="x86_64")Explicit Node Routing
# Run on Linux builder
result = await offload_to("podman run -it ubuntu:22.04", node_id="macpro51")
# Run on Mac Studio
result = await offload_to("swift build", node_id="mac-studio")Parallel Execution
# Run tests across cluster
results = await parallel_execute([
"pytest tests/unit/",
"pytest tests/integration/",
"pytest tests/e2e/"
])Cluster Status
# Get cluster health before heavy operations
status = await cluster_status()
# Returns:
# {
# "local_node": "macpro51",
# "nodes": {
# "macpro51": {"cpu_percent": 15.2, "memory_percent": 45.3, ...},
# "mac-studio": {"cpu_percent": 8.1, "memory_percent": 32.1, ...},
# ...
# }
# }Cluster Nodes
Node | OS | Arch | Capabilities | Specialties |
| Linux | x86_64 | docker, podman, raid, nvme, compilation, testing, tpu | compilation, testing, containerization, benchmarking |
| macOS | ARM64 | orchestration, coordination, temporal, mlx-gpu, arduino | orchestration, coordination, monitoring |
| macOS | ARM64 | research, documentation, analysis | research, documentation, mobile |
| macOS | ARM64 | ollama, inference, model-serving, llm-api | ollama-inference, model-serving |
Offload Patterns
Commands matching these patterns are automatically offloaded:
Build:
make,cargo,npm,yarn,pnpmTest:
pytest,jest,mocha,testCompile:
gcc,g++,clangContainer:
docker,podman,kubectlFile ops:
rsync,scp,tar,zip,find,grep -r
Commands that stay local:
Simple:
ls,pwd,cd,echo,cat,head,tail,which,type
Security
Shell Injection Prevention
All commands use subprocess.run() with list arguments where possible:
# SAFE: List arguments
subprocess.run(["ssh", "-o", "ConnectTimeout=5", f"{user}@{ip}", command])
# Complex shell commands are validated before executionCommand Validation
Commands are validated for dangerous patterns:
rm -rf /rm -rf /*> /dev/sdaFork bombs
And more...
SSH Configuration
StrictHostKeyChecking=accept-new- Accept new hosts but verify returning hostsBatchMode=yes- Non-interactive mode for scriptingConfigurable timeouts and retries
Development
Running Tests
# Install dev dependencies
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# With coverage
pytest tests/ --cov=cluster_execution_mcp --cov-report=htmlProject Structure
cluster-execution-mcp/
├── src/cluster_execution_mcp/
│ ├── __init__.py # Package exports
│ ├── config.py # Configuration, validation, node definitions
│ ├── router.py # Task routing and IP resolution
│ └── server.py # FastMCP server and tools
├── tests/
│ ├── conftest.py # Pytest fixtures
│ ├── test_config.py # Config module tests (29 tests)
│ ├── test_router.py # Router module tests (21 tests)
│ └── test_server.py # Server and tool tests (21 tests)
└── pyproject.toml # Package configurationCLI Interface
# Submit a command
cluster-router submit "make -j8 all"
# Check task status
cluster-router status <task_id>
# Show cluster status
cluster-router cluster-statusMonitoring
Check cluster health before operations:
User: "Show me cluster status"
Claude Code: cluster_status tool
Output:
macpro51:
CPU: 45.2%
Memory: 18.3%
Load: 3.21
Status: healthy
mac-studio:
CPU: 22.1%
Memory: 54.7%
Load: 2.15
Status: healthy
macbook-air:
CPU: 12.8%
Memory: 38.2%
Load: 1.03
Status: healthyTroubleshooting
MCP server not loading:
# Check config
cat ~/.claude.json | jq '.mcpServers["cluster-execution"]'
# Test server import
python3 -c "from cluster_execution_mcp.server import main; print('OK')"Node unreachable:
# Test SSH connectivity
ssh marc@macpro51.local hostname
ssh marc@Marcs-Mac-Studio.local hostname
# Check with fallback IP
ssh marc@192.168.1.183 hostnameCommands timing out:
# Increase timeout via environment
export CLUSTER_CMD_TIMEOUT=600 # 10 minutes
export CLUSTER_SSH_TIMEOUT=10 # 10 secondsChangelog
v0.2.0
New Features:
Proper package structure with pyproject.toml
Environment-based configuration (no hardcoded credentials)
Shared config module with validation functions
Retry logic for SSH connectivity
IP resolution caching with TTL
Inference node support
Security Improvements:
Eliminated shell injection vulnerabilities
Command validation for dangerous patterns
IP validation rejecting loopback/Docker/link-local
SSH host key handling (accept-new)
Code Quality:
Full type hints throughout codebase
Replaced bare except clauses with specific exceptions
Added comprehensive logging
71 unit tests with mocking
Bug Fixes:
Fixed darwin/macos OS alias handling
Proper timeout handling in SSH operations
Better error messages for failed operations
v0.1.0
Initial release with basic cluster execution
License
MIT
Part of the AGI Agentic System
See also:
Node Chat MCP - Inter-node communication
Enhanced Memory MCP - Persistent memory with RAG
Agent Runtime MCP - Goals and task queue
Available Tools
4 toolscluster_bashA
Execute bash command with automatic cluster routing.
Commands are automatically routed to optimal nodes based on:
Current cluster load (CPU, memory, load average)
Command characteristics (build/test/compile patterns)
Node capabilities (OS, architecture)
Heavy commands (make, cargo, pytest, docker, etc.) are automatically offloaded. Simple commands (ls, cat, echo) run locally for speed.
Parameters:
command (required): Bash command to execute
requires_os (optional): Force specific OS (linux/darwin)
requires_arch (optional): Force specific architecture (x86_64/arm64)
auto_route (optional): Enable auto-routing (default: true)
Returns execution result with node info and output.
Inputs: command (required), auto_route, requires_os, requires_arch. Returns: result
cluster_statusA
Get current cluster status and load distribution.
Shows real-time metrics for all cluster nodes:
CPU usage percentage
Memory usage percentage
1-minute load average
Active task count
Health status (healthy/overloaded)
Reachability
Use this to:
Check cluster health before heavy operations
Determine optimal node for manual routing
Debug cluster connectivity issues
Monitor distributed execution
Returns JSON with status for each node.
Inputs: no named parameters. Returns: result
offload_toA
Explicitly route command to specific cluster node.
Use when you need to:
Run Linux-specific commands -> offload to macpro51
Test on specific architecture
Balance load manually
Debug node-specific issues
Available nodes:
macpro51: Linux x86_64 builder (docker, podman, compilation)
mac-studio: macOS ARM64 orchestrator
macbook-air: macOS ARM64 researcher
Parameters:
command (required): Bash command to execute
node_id (required): Target node ID
Returns execution result from specified node.
Inputs: command (required), node_id (required). Returns: result
parallel_executeA
Execute multiple commands in parallel across cluster.
Distributes commands across available nodes for maximum parallelism. Use for:
Running test suites across multiple files
Parallel builds
Batch processing
Load testing
Commands are automatically distributed based on node availability and load.
Parameters:
commands (required): List of bash commands to execute in parallel
Returns list of results, one per command, with execution details.
Inputs: commands (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: cluster_bash for general command execution, cluster_status for monitoring, offload_to for explicit routing to a node, and parallel_execute for batch execution. There is no overlap in functionality.
Tool names follow mixed conventions: cluster_bash and cluster_status share a prefix, but offload_to and parallel_execute use verb phrases without the prefix. The naming patterns are inconsistent, making it harder to infer the pattern at a glance.
With 4 tools, the server is lean but covers the core functions of cluster execution. It could benefit from a dedicated node listing tool, but the count is appropriate for its scope.
The tool set covers the key operations: executing commands, getting status, explicit routing, and parallel execution. Minor gaps like the absence of a tool to list available nodes dynamically are present but do not severely hinder typical workflows.
Maintenance
Related MCP Connectors
Task manager for AI agents. Orchestrate agents to achieve large goals in unified control plane.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
On-demand GPU nodes for agents: create nodes, run commands, and submit jobs, billed by the minute.
AI work orchestration for plans, tasks, teams, and coding-agent dispatch.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceTransforms idle LAN machines into a unified compute cluster for AI agents to offload CPU-intensive tasks like simulations and backtesting. It provides a broker-worker architecture that integrates with MCP-compatible tools to distribute workloads across a local network.5MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to execute CLI commands and scripts for system deployment and management tasks, with support for directory listing, system info, and deployment templates.46 PyPI1MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to orchestrate a heterogeneous machine fleet via SSH, with unified command execution, file transfer, and dispatch of coding agents across platforms.2Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables managing SSH-managed clusters with tools for executing commands, file operations, and tmux sessions across multiple nodes.1MIT