MCP server de libtmux
Commit 12 nov 2026Permite que los agentes de IA gestionen sesiones, ventanas y paneles de tmux mediante la ejecución de comandos, la lectura de la salida de la terminal y la orquestación de entornos de terminal.
También conocido como tmux-python/libtmux-mcp
- Stars
- 14
- Herramientas
- —
- Descargas, 30 días
- —
- Última versión
- —
- Último commit
- 12 nov 2026
- Licencia
- MIT
¿Qué es libtmux MCP?
Permite que los agentes de IA gestionen sesiones, ventanas y paneles de tmux mediante la ejecución de comandos, la lectura de la salida de la terminal y la orquestación de entornos de terminal.
Resumen generado a partir del README del proyecto
Acerca del MCP server de libtmux
libtmux-mcp permite gestionar entornos de terminal y procesos de larga duración desde un agente de IA. Este MCP server actúa como un puente entre los clientes de Model Context Protocol y tmux, permitiendo que los agentes creen sesiones, gestionen ventanas y controlen paneles individuales. Está diseñado para desarrolladores que utilizan herramientas como Claude Desktop, Claude Code, Codex CLI o Gemini CLI para dar a sus asistentes de IA una interacción directa con un entorno de terminal.
Los usuarios pueden configurar el servidor localmente usando uvx o añadiéndolo a la configuración de su cliente. El servidor incluye herramientas especializadas para una orquestación de terminal sofisticada, como run_command para ejecutar comandos de shell con su estado de salida, wait_for_text para monitorear la salida sin realizar consultas constantes, y capture_since para leer únicamente las nuevas filas de la terminal. También ofrece gestión de paneles mediante herramientas como split_window, resize_pane y send_keys_batch para interactuar con interfaces de usuario basadas en texto.
Esta implementación se centra en la eficiencia y la seguridad. Utiliza la supresión de historial para mantener los comandos del agente fuera del historial de la shell e incluye salvaguardas para evitar que un agente mate accidentalmente su propia sesión host. Los desarrolladores pueden refinar aún más las capacidades del agente utilizando la variable de entorno LIBTMUX_TOOLSETS para incluir o excluir grupos de herramientas específicos como inspect, manage, execute o teardown.
Qué puedes hacer con él
- 1Ejecución automatizada de pruebasPide a un agente que inicie una nueva sesión de tmux y ejecute una suite de pruebas específica mientras monitorea los resultados.
Escrito a partir del README del proyecto. Cada caso de uso se verifica con una cita del mismo.
Verificaciones automáticas
Ejecutado 14 nov 2026Informe completo →Aún no verificado. Un servidor necesita una puntuación de 80, ningún hallazgo grave y suficientes datos para que podamos revisarlo. Cómo funcionan las verificaciones · Qué corregir para obtener más puntos
- Repositorio de origen vinculado y accesibletmux-python/libtmux-mcp is public and reachablegithub.com/tmux-python/libtmux-mcp ↗Aprobado
- El paquete indica este repositorio como su origenNo verificado
- Procedencia de la compilación (atestación de Sigstore)No verificado
- Licencia de código abierto (OSI)MITspdx.org/licenses/MIT.html ↗Aprobado
- Commit o lanzamiento en el último añoLast commit or release 2026-11-12github.com/tmux-python/libtmux-mcp ↗Aprobado
- OpenSSF ScorecardNo verificado
- El nombre del paquete no es similar a un paquete popularNo verificado
- No hay avisos críticos en el paquete ni en sus dependenciasNo verificado
- Sin instrucciones ocultas para el modelo0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersAprobado
- Las herramientas destructivas están etiquetadasNo verificado
- El endpoint remoto responde al handshake de MCPNo verificado
README
Ver en GitHublibtmux-mcp
A Model Context Protocol server for tmux, built on libtmux.
[!WARNING] Alpha. Releases carry an
-alphaprerelease tag. The API is not settled, and any release may change or remove exported identifiers without a deprecation period. Pin an exact version. Not recommended for production.
Give your AI agent hands inside the terminal — create sessions, run commands, read output, orchestrate panes.
Tools
| Module | Tools |
|---|---|
| Server | list_servers, list_sessions, create_session, kill_server, get_server_info |
| Batch | call_read_tools_batch |
| Session | list_windows, get_session_info, create_window, rename_session, select_window, kill_session |
| Window | list_panes, get_window_info, split_window, rename_window, select_layout, resize_window, move_window, kill_window |
| Pane | run_command, send_keys, send_keys_batch, paste_text, capture_pane, capture_since, snapshot_pane, search_panes, find_pane_by_position, get_pane_info, wait_for_text, wait_for_channel, signal_channel, display_message, select_pane, swap_pane, resize_pane, set_pane_title, clear_pane, pipe_pane, enter_copy_mode, exit_copy_mode, respawn_pane, kill_pane |
| Options | show_option, set_option |
| Environment | show_environment, set_environment |
| Buffers | load_buffer, paste_buffer, show_buffer, delete_buffer |
| Hooks | show_hooks, show_hook |
Quickstart
Requirements: Python 3.11+, tmux >= 3.2a on $PATH.
The distribution is libtmux-mcp, the import is libtmux_mcp, and the
installed executable is libtmux-mcp.
Install and run:
$ uvx libtmux-mcp
Claude Code
$ claude mcp add tmux -- uvx libtmux-mcp
Codex CLI
$ codex mcp add tmux -- uvx libtmux-mcp
Gemini CLI
$ gemini mcp add tmux uvx -- libtmux-mcp
Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"tmux": {
"command": "uvx",
"args": ["libtmux-mcp"]
}
}
}
More clients and JSON config: client setup docs
What it feels like
You: Create a session called "api" and run
pytest tests/api/ -xin it.Agent: Created session
apiwith windowtests. Running pytest now. Here's the output — 14 passed, 2 failed. The failures are intest_auth.py::test_token_refreshandtest_auth.py::test_expired_session. Want me to open those files?
The agent manages tmux directly. No copy-pasting terminal output. No switching windows to check on long-running processes.
When the server earns its keep
For a single tmux send-keys, the server doesn't. It earns its keep
the moment the agent has to wait, inspect, or avoid damaging the
terminal it is using — pytest finishing, a dev server printing its
port, a deploy log settling. The difference then is not more access
to tmux, but a better place to put the control loop.
The server-side moves are:
Running. run_command
sends an authored shell command, waits for deterministic completion,
and returns exit status plus tail-preserved output as one typed value.
The command and its completion signal reach the shell as one
space-prefixed event, so best-effort
history suppression
keeps agent-generated input out of shell history by default. The
alternative — hand-rolled send-keys plus wait-for plus a pane
capture — leaves every typed command, signal included, in shell
history.
Driving. send_keys_batch
sends several ordered raw-input operations for TUIs and persistent
shell interaction. It is deliberately not a workflow DSL; command
completion stays in run_command, and repeated observation stays in
capture_since.
Waiting. wait_for_text
blocks inside the server until a condition fires for output the agent
does not author. The alternative is the model polling capture-pane
in a loop, paying both context tokens and round-trip latency for every
turn.
Reading. snapshot_pane
returns content, cursor, copy-mode state, and scroll offset as one
typed value. The alternative is several tmux invocations stitched
together with regex.
Observing. capture_since
returns a cursor with the current pane content, then returns only
newly written or rewritten rows on follow-up calls. The alternative is
re-sending the same scrollback to the model on every check.
Guarding. The server detects the agent's own pane across sockets
and declines to end its own — kill_session
on itself fails loudly instead of silently terminating the host
environment the agent is running in. LIBTMUX_TOOLSETS
(inspect, manage, execute, teardown) drops whole toolsets from the
client's tool list before any prompt is built. The sets are unordered, so
inspect,teardown is a legal surface. Dropping one is inventory and MCP
tool-call configuration, not containment: an enabled execute tool can type
the equivalent of anything it hides.
Documentation
Full docs, guides, and tool reference: libtmux-mcp.git-pull.com
Development
Clone and install:
$ git clone https://github.com/tmux-python/libtmux-mcp.git
$ cd libtmux-mcp
$ uv sync --all-extras --dev
Run the server locally:
$ uv run libtmux-mcp
Run tests:
$ uv run pytest
See CONTRIBUTING.md for the gates, and WRITING.md for how this project writes prose, docstrings, and MCP tool descriptions.
Related projects
- libtmux — Python API for tmux
- tmuxp — tmux session manager
- The Tao of tmux — the book
Attribution
Please use the following BibTeX template to cite libtmux-mcp in scientific discourse:
@misc{libtmux-mcp,
author = {Tony Narlock},
year = {2026},
note = {https://libtmux-mcp.git-pull.com},
title = {libtmux-mcp: MCP server for tmux}
}
License
MIT
Preguntas sobre libtmux MCP
¿Está este servidor listo para entornos de producción?
No, el servidor está actualmente en fase Alpha, lo que significa que la API no es definitiva y las versiones pueden cambiar o eliminar identificadores sin previo aviso.
¿Puede el agente ejecutar comandos sin ensuciar el historial de la shell?
Sí, la herramienta run_command utiliza la supresión de historial para evitar que la entrada generada por el agente se guarde en el historial de la shell de forma predeterminada.