Cuba-Exec
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., "@Cuba-Exec start a background npm dev server"
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.
🚀 Cuba-Exec
Advanced shell command execution for AI agents — A Model Context Protocol (MCP) server with security policy engine, process lifecycle management, bounded output capture, POSIX signals, and token-efficient responses.
6 tools. Zero configuration. POSIX-native. Security by default.
Why Cuba-Exec?
Existing command execution MCPs are thin wrappers over subprocess.run. Cuba-Exec solves the real problems:
Problem | Existing MCPs | Cuba-Exec |
Output overflow (cat /dev/urandom) | ❌ OOM crash | ✅ 64KB bounded |
Background processes | ❌ Sync only | ✅ Start/status/signal |
Kill child processes (npm run dev) | ❌ Orphaned children | ✅ Process group kill (setsid) |
Send stdin (REPLs, prompts) | ❌ Not supported | ✅ Full stdin pipe |
POSIX signals (SIGTERM, SIGKILL) | ❌ Not supported | ✅ 5 signals + graceful shutdown |
Command allowlist/blocklist | ⚠️ Some | ✅ Both + shell operator validation |
Directory restriction | ⚠️ Rare | ✅ Path-resolved anti-traversal |
Audit logging | ❌ None | ✅ Structured JSON to stderr |
Token-efficient output | ❌ Verbose JSON | ✅ TOON compact format |
Idle process cleanup | ❌ Resource leak | ✅ 1-hour TTL auto-cleanup |
Fork bomb protection | ❌ None | ✅ Semaphore(20) |
Process discovery | ❌ None | ✅ List all managed processes |
Related MCP server: Shell MCP Server
Quick Start
1. Prerequisites
Python 3.14+
Linux/macOS (POSIX required for process groups)
2. Install
git clone https://github.com/LeandroPG19/cuba-exec.git
cd cuba-exec
uv venv && uv pip install -e .3. Configure your AI editor
{
"mcpServers": {
"cuba-exec": {
"command": "/path/to/cuba-exec/.venv/bin/python",
"args": ["-m", "cuba_exec"]
}
}
}Zero environment variables needed. Zero configuration files. It just works — with 25 dangerous commands blocked by default.
The 6 Tools
run — Execute and wait
run(command="ls -la", cwd="/tmp", timeout_ms=5000)Parameter | Type | Default | Description |
| string | required | Shell command |
| string | None | Working directory |
| dict | None | Environment variables (merged with current) |
| int | 30000 | Timeout in milliseconds |
| int | 65536 | Output buffer size (bytes) |
| string | /bin/sh | Shell executable |
Response:
[exit:0 time:12ms trunc:no]
total 156
drwxrwxrwt 22 root root 4096 Mar 8 2026 .
...start — Background process
start(command="npm run dev", cwd="/app")Response:
[pid:12345 state:running]
Background process started. Use status(12345) to check output.status — Check background process
status(pid=12345, tail_bytes=4096)Response:
[pid:12345 state:running exit:- time:5432ms bytes:8192 trunc:no]
Server running on http://localhost:3000send_signal — POSIX signals
send_signal(pid=12345, sig="SIGTERM")SIGTERM triggers graceful shutdown: SIGTERM → wait 5s → SIGKILL.
Valid signals: SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.
send_input — stdin pipe
send_input(pid=12345, stdin="print('hello')\n")For interactive processes (Python REPL, bash prompt, etc.).
list_processes — Process discovery
list_processes()Response:
[processes:2]
pid:12345 state:running exit:- time:5432ms bytes:8192 cmd:npm run dev
pid:12346 state:completed exit:0 time:1200ms bytes:256 cmd:echo done🛡️ Security Policy Engine
Cuba-Exec includes a multi-layer security engine — the most comprehensive of any MCP command server.
Security Layers
Layer | Description | Config |
Command Allowlist | Only listed commands can execute |
|
Command Blocklist | Dangerous commands always rejected |
|
Shell Operator Validation | Validates each sub-command after | Automatic |
Directory Restriction | Restrict |
|
Audit Logging | Structured JSON log of every execution |
|
Default Behavior (Zero Config)
Out of the box, Cuba-Exec blocks 25 dangerous commands:
rm, dd, mkfs, shutdown, reboot, halt, poweroff, init, systemctl,
passwd, chown, chmod, chgrp, mount, umount, fdisk, parted,
iptables, nft, ip6tables, crontab, at, useradd, userdel,
groupadd, groupdel, visudoProduction Hardening
export CUBA_EXEC_ALLOWED_COMMANDS="ls,cat,echo,grep,find,head,tail,wc,git,python3,node,npm"
export CUBA_EXEC_BLOCKED_COMMANDS="rm,dd,mkfs,shutdown"
export CUBA_EXEC_ALLOWED_DIRS="/home/user/project,/tmp"
export CUBA_EXEC_AUDIT=1Shell Operator Bypass Prevention
ls && rm -rf / — the rm after && is validated against blocklist/allowlist too.
Operators parsed: ;, &&, ||, | — each sub-command checked independently.
Audit Log (stderr)
{"ts":"2026-03-08T15:00:00-0600","event":"exec","command":"ls -la","pid":12345,"exit":0,"ms":12,"ok":true}Output Format (TOON)
All responses use Token-Oriented Object Notation — compact headers that save ~200 tokens per tool call vs verbose JSON.
[exit:0 time:1543ms trunc:no]
...output...Error Codes
Error | Exit Code | Field | Example |
Command not found | 127 |
|
|
Permission denied | 126 |
|
|
Timeout | -1 |
|
|
Signal killed | -9 |
| Process killed by signal |
Blocked by policy | — |
|
|
Head+Tail Output Buffer — Shannon (1948)
Command output has high entropy at the extremes (preamble + results/errors) and low entropy in the middle (progress bars, repetitive logs).
┌─────────────┬───────────────────────────────┬──────────────────────────────────────────┐
│ Head (25%) │ Truncated middle │ Tail (75%) │
│ ~16KB │ [... N bytes truncated ...] │ ~48KB (ring buffer) │
└─────────────┴───────────────────────────────┴──────────────────────────────────────────┘Head: First 25% of buffer — captures headers, version info
Tail: Last 75% via ring buffer — captures results, errors (highest entropy)
Ring buffer: O(1) write, O(C) memory (Cormen et al., CLRS 4th ed.)
Default: 64KB per process. Max memory: 20 × 64KB = 1.28MB
POSIX Process Groups — IEEE Std 1003.1
npm run dev spawns child processes. Sending SIGTERM to the parent doesn't kill children.
Cuba-Exec creates process groups via setsid:
asyncio.create_subprocess_exec(..., start_new_session=True)
os.killpg(os.getpgid(pid), signal.SIGTERM) # Kills entire treeGraceful Shutdown
SIGTERM → wait 5s → SIGKILL (if still alive)Two-phase shutdown (Stevens & Rago, 2013): SIGTERM allows cleanup, SIGKILL is uncatchable.
Configuration
All defaults work out of the box. Override via environment variables:
Setting | Default | Env Var |
Max concurrent processes | 20 |
|
Output buffer size | 64KB |
|
Idle process TTL | 1 hour |
|
Shutdown timeout | 5s |
|
Allowed commands | — (all) |
|
Blocked commands | 25 defaults |
|
Allowed directories | — (all) |
|
Audit logging | off |
|
Architecture
cuba-exec/
├── pyproject.toml # 1 dependency: fastmcp
└── src/
└── cuba_exec/
├── __init__.py
├── __main__.py # Entry point
├── server.py # FastMCP 6 tool definitions (~105 LOC)
├── security.py # SecurityPolicy engine (~135 LOC)
├── process_manager.py # Lifecycle FSM + signals + TTL (~520 LOC)
└── output_buffer.py # Head+Tail ring buffer (~110 LOC)Total: ~880 LOC. FastMCP SDK handles protocol boilerplate.
Dependencies (1 total)
Package | Purpose |
| MCP protocol server — auto tool schemas from type hints, Pydantic validation |
Everything else is Python stdlib: asyncio, os, signal, time, json, re, pathlib.
Part of the Cuba Ecosystem
Project | Purpose |
Persistent memory — knowledge graph, Hebbian learning | |
Sequential reasoning — cognitive engine, NLI, MCTS | |
Web search — research, scraping, validation, documentation lookup | |
Cuba-Exec | Shell execution — process lifecycle, security, bounded output, POSIX signals |
Together: memory + reasoning + search + execution — the four pillars of capable AI agents.
Academic References
# | Citation | Used For |
1 | Yang et al. (2024). "SWE-agent: Agent-Computer Interfaces." NeurIPS | ACI design, output truncation, guardrails |
2 | Shannon (1948). "A Mathematical Theory of Communication" | Information-theoretic output strategy |
3 | IEEE Std 1003.1-2024. "POSIX.1: System Interfaces" | Process groups, setsid, signals |
4 | Cormen et al. (2022). "Introduction to Algorithms." 4th ed. | Ring buffer O(1) analysis |
5 | Dijkstra (1965). "Cooperating Sequential Processes" | Semaphore concurrency limiting |
6 | Stevens & Rago (2013). "APUE" 3rd ed. | Process lifecycle, graceful shutdown |
7 | TOON (2025). "Token-Oriented Object Notation" | 95-97% token reduction |
8 | OWASP (2025). "Top 10 for Agentic Applications" | Security policy design, allowlist/blocklist |
License
CC BY-NC 4.0 — Free to use and modify, not for commercial use.
Author
Leandro Pérez G.
GitHub: @LeandroPG19
Email: leandropatodo@gmail.com
Available Tools
6 toolslist_processesA
List all managed background processes with state and metadata.
Returns PID, state, exit code, duration, bytes captured, and command preview for every background process currently tracked by the server.
Inputs: no named parameters. Returns: result
runA
Execute a shell command synchronously and wait for completion.
Returns exit code, duration, and captured stdout+stderr. Output is bounded by max_output (default 64KB) using head+tail capture.
Inputs: command (required), cwd, env, shell, +2 more. Returns: result
send_inputA
Send text to a running process's stdin.
Use this for interactive processes (REPLs, prompts). The text is encoded as UTF-8 and written to the process stdin pipe.
Inputs: pid (required), stdin (required). Returns: result
send_signalA
Send a POSIX signal to a process group.
SIGTERM triggers graceful shutdown: SIGTERM → wait 5s → SIGKILL. Valid signals: SIGTERM, SIGKILL, SIGINT, SIGHUP, SIGQUIT.
Inputs: pid (required), sig. Returns: result
startA
Start a background process and return its PID.
The process runs asynchronously. Use status() to check output, signal() to send signals, and input() to send stdin.
Inputs: command (required), cwd, env, shell. Returns: result
statusA
Check background process state, exit code, and tail output.
Returns process state (running/completed/timed_out), duration, total bytes captured, truncation status, and recent output.
Inputs: pid (required), tail_bytes. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct operation: foreground execution, background start, status query, signal sending, stdin input, and process listing. No overlap in purpose, and the descriptions make the boundaries clear.
There is a mix of conventions: 'status' is a noun, 'run' and 'start' are bare verbs, while 'send_signal', 'send_input', and 'list_processes' follow verb_noun. The send_* and list_* group is consistent, but the others break the pattern.
Six tools cover the core process execution and management workflow without unnecessary bloat. The count feels well-scoped for this domain.
The set provides complete lifecycle coverage: synchronous execution, background starts, status checks, signal handling, stdin interaction, and process enumeration. No obvious gaps for a process execution server.
Maintenance
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Remote MCP server exposing your Node Command fleet (files, shell, processes, browser) to AI hosts.
Secure Linux sandboxes for AI agents, as MCP tools.
AgentGuard — 20-tool AI safety MCP: policy preflight, risk scoring, audit logging, rate limits.
Related MCP Servers
- AlicenseBqualityDmaintenanceA secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.20389 npm7MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.7MIT
- AlicenseBqualityFmaintenanceA server that uses the Model Context Protocol (MCP) to allow AI agents to safely execute shell commands on a host system.180 npm9MIT
- FlicenseNot gradedqualityNot gradedmaintenanceA secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.-