Skip to main content
Glama

🚀 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

command

string

required

Shell command

cwd

string

None

Working directory

env

dict

None

Environment variables (merged with current)

timeout_ms

int

30000

Timeout in milliseconds

max_output

int

65536

Output buffer size (bytes)

shell

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

send_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

CUBA_EXEC_ALLOWED_COMMANDS

Command Blocklist

Dangerous commands always rejected

CUBA_EXEC_BLOCKED_COMMANDS

Shell Operator Validation

Validates each sub-command after ;, &&, ||, |

Automatic

Directory Restriction

Restrict cwd to allowed paths (anti-traversal)

CUBA_EXEC_ALLOWED_DIRS

Audit Logging

Structured JSON log of every execution

CUBA_EXEC_AUDIT

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, visudo

Production 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=1

Shell 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

ENOENT

nonexistent_binary

Permission denied

126

EACCES

cat /etc/shadow

Timeout

-1

TIMEOUT

sleep 60 with 1s timeout

Signal killed

-9

SIGKILL

Process killed by signal

Blocked by policy

—

BLOCKED

rm -rf /


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 tree

Graceful 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

CUBA_EXEC_MAX_PROCS

Output buffer size

64KB

CUBA_EXEC_BUFFER_SIZE

Idle process TTL

1 hour

CUBA_EXEC_TTL

Shutdown timeout

5s

CUBA_EXEC_SHUTDOWN_TIMEOUT

Allowed commands

— (all)

CUBA_EXEC_ALLOWED_COMMANDS

Blocked commands

25 defaults

CUBA_EXEC_BLOCKED_COMMANDS

Allowed directories

— (all)

CUBA_EXEC_ALLOWED_DIRS

Audit logging

off

CUBA_EXEC_AUDIT


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

fastmcp

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

Cuba-Memorys

Persistent memory — knowledge graph, Hebbian learning

Cuba-Thinking

Sequential reasoning — cognitive engine, NLI, MCTS

Cuba-Search

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.

Available Tools

6 tools
list_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

    A4.1/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count5/5

    Six tools cover the core process execution and management workflow without unnecessary bloat. The count feels well-scoped for this domain.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A secure MCP server for executing whitelisted shell commands with resource and timeout controls, designed for integration with Claude and other MCP-compatible LLMs.
      20
      389 npm
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that allows LLMs to execute shell commands and receive their output in a controlled manner.
      7
      MIT
    • F
      license
      Not graded
      quality
      Not graded
      maintenance
      A secure and pluggable MCP server to run terminal commands on your local machine or cloud server — remotely, safely, and with LLMs or agentic clients.
      -