Introduction

Post-Exploitation tmux MCP is a Model Context Protocol server that exposes essential tmux features as MCP tools — giving AI agents a fully-featured terminal multiplexer for post-exploitation operations. Every command is validated through built-in guardrails that block destructive system commands before they execute. Built with FastMCP, it lets any MCP-compatible client (AI agents, automation frameworks, etc.) create sessions, spawn windows, split panes, and run commands — all while preventing accidental or malicious system damage.

Features

This server exposes 14 tools across the following categories:

• Session management:

  • Create detached sessions

  • List all active sessions

  • Kill specific sessions

• Window management:

  • Create new windows in a session

  • List windows in a session

  • Kill specific windows

• Pane management:

  • Split panes vertically or horizontally

  • List panes with running command & PID info

  • Kill specific panes

• Command execution (all guarded):

  • execute_command — run a command with guardrail validation

  • send_keys — send keystrokes to a pane (guarded when Enter is pressed)

  • capture_pane — read pane output with trailing blanks stripped

• Utility:

  • validate_command_safety — pre-check a command without executing

  • kill_server — kill the entire tmux server

• Built-in guardrails that block:

  • File destruction — rm -rf /, shred, wipefs

  • Disk operations — mkfs, dd if=, fdisk, parted

  • Fork bombs — :(){ :|:& };:

  • System shutdown — shutdown, reboot, halt, init 0/6

  • Critical process killing — kill -9 1, killall -9

  • Permission bombs — chmod -R 777 /

  • Dangerous redirects — > /etc/passwd, > /etc/shadow

  • Network destruction — iptables -F

  • Log tampering — > /var/log/, history -c

  • Obfuscated execution — curl ... | sh, base64 -d | sh

Installation

Just clone the repository and install the dependencies:

git clone https://github.com/RaghavanSV/Tmux-MCP.git
cd 'Tmux-MCP'
pip install -r requirements.txt

Prerequisite: tmux must be installed on the target machine.

Usage

Run the MCP server

python server.py

Test with the interactive client

python client.py

The client connects to server.py via stdio, lists available tools, and gives you an interactive REPL to call them.

Connect from an MCP client (e.g. AI agent)

{
  "mcpServers": {
    "post-exploitation-tmux": {
      "command": "python3",
      "args": ["path/to/Tmux-MCP/server.py"]
    }
  }
}

Generate a session, create a window, and run a guarded command

# Using the interactive client
> create_session("pentest", "recon")
> execute_command("pentest", "recon", "0", "nmap -sV 192.168.1.1")
> capture_pane("pentest", "recon", "0")

Tool Reference

Sessions

Windows

Panes

Command Execution (Guarded)

Utility

Project Structure

Post-Exploitation/
├── server.py            # FastMCP server — 14 tools
├── tmux_wrapper.py      # Thin Python wrapper around tmux CLI
├── guardrails.py        # Command validation & safety checks
├── client.py            # Interactive MCP test client
├── test_guardrails.py   # Guardrails unit tests
├── requirements.txt     # Python dependencies
└── README.md            # This file

Testing

Run guardrail tests

python test_guardrails.py

Test MCP tools interactively

python client.py

References

https://github.com/tmux/tmux
https://github.com/jlowin/fastmcp
https://modelcontextprotocol.io
https://github.com/tmux-python/libtmux

Disclaimer

Use this project under your own responsibility! This tool is intended for authorized penetration testing and security research only. Unauthorized use against systems you do not own or have explicit permission to test is illegal. The author is not responsible for any misuse of this project.

License

This project is under MIT license

Copyright © 2025, RaghavanSV