libtmux MCP server
2026년 11월 12일 커밋AI 에이전트가 명령어를 실행하고 터미널 출력을 읽으며 터미널 환경을 오케스트레이션하여 tmux 세션, 윈도우, 팬을 관리할 수 있도록 합니다.
다른 이름 tmux-python/libtmux-mcp
- 스타
- 14
- Tools
- —
- 다운로드, 30일
- —
- 최신 버전
- —
- 마지막 커밋
- 2026년 11월 12일
- 라이선스
- MIT
libtmux MCP란?
AI 에이전트가 명령어를 실행하고 터미널 출력을 읽으며 터미널 환경을 오케스트레이션하여 tmux 세션, 윈도우, 팬을 관리할 수 있도록 합니다.
프로젝트 README에서 생성된 요약
libtmux MCP server 정보
libtmux-mcp는 AI 에이전트 내부에서 터미널 환경과 장시간 실행되는 프로세스를 관리할 수 있게 해줍니다. 이 MCP server는 Model Context Protocol 클라이언트와 tmux 사이의 가교 역할을 하여, 에이전트가 세션을 생성하고 윈도우를 관리하며 개별 팬을 제어할 수 있도록 지원합니다. Claude Desktop, Claude Code, Codex CLI 또는 Gemini CLI와 같은 도구를 사용하는 개발자가 AI 어시스턴트에게 터미널 환경과의 직접적인 상호작용 권한을 부여할 수 있도록 설계되었습니다.
사용자는 uvx를 사용하거나 클라이언트 설정에 추가하여 로컬에 서버를 구축할 수 있습니다. 이 서버는 정교한 터미널 오케스트레이션을 위한 특화된 도구들을 포함하고 있습니다. 종료 상태와 함께 셸 명령어를 실행하는 run_command, 지속적인 폴링 없이 출력을 모니터링하는 wait_for_text, 새로운 터미널 행만 읽어오는 capture_since 등이 대표적입니다. 또한 split_window, resize_pane, 텍스트 기반 사용자 인터페이스 상호작용을 위한 send_keys_batch와 같은 도구를 통해 팬 관리 기능을 제공합니다.
본 구현은 효율성과 안전성에 중점을 둡니다. 에이전트 명령어가 셸 히스토리에 남지 않도록 히스토리 억제 기능을 사용하며, 에이전트가 실수로 자신의 호스트 세션을 종료하는 것을 방지하는 안전장치를 포함합니다. 개발자는 LIBTMUX_TOOLSETS 환경 변수를 사용하여 inspect, manage, execute, teardown과 같은 특정 도구 그룹을 포함하거나 제외함으로써 에이전트의 기능을 더욱 세밀하게 조정할 수 있습니다.
활용 사례
- 1자동화된 테스트 실행에이전트에게 새로운 tmux 세션을 시작하고 특정 테스트 스위트를 실행하면서 결과를 모니터링하도록 요청합니다.
프로젝트의 README를 바탕으로 작성되었습니다. 모든 활용 사례는 해당 내용의 인용문과 대조하여 확인합니다.
자동 검사
2026년 11월 14일에 실행됨전체 보고서 →아직 인증되지 않았습니다. 서버는 80점 이상의 점수, 심각한 결함 없음, 그리고 검사에 충분한 데이터를 갖추어야 합니다. 검사 방식 · 점수를 높이기 위해 수정할 항목
- 소스 저장소 연결 및 접근 가능tmux-python/libtmux-mcp is public and reachablegithub.com/tmux-python/libtmux-mcp ↗통과
- 패키지가 이 저장소를 소스로 명시검사되지 않음
- 빌드 출처(Sigstore 증명)검사되지 않음
- 오픈 소스 라이선스 (OSI)MITspdx.org/licenses/MIT.html ↗통과
- 최근 1년 내 커밋 또는 릴리스Last commit or release 2026-11-12github.com/tmux-python/libtmux-mcp ↗통과
- OpenSSF Scorecard검사되지 않음
- 패키지 이름이 인기 패키지와 유사하지 않음검사되지 않음
- 패키지 및 해당 종속성에 중요한 보안 권고 없음검사되지 않음
- 모델에 대한 숨겨진 지침 없음0 tool descriptions and the README read; no override phrases, credential paths or hidden characters통과
- 파괴적인 도구에 라벨 표시됨검사되지 않음
- 원격 엔드포인트가 MCP 핸드셰이크에 응답검사되지 않음
README
GitHub에서 보기libtmux-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
libtmux MCP 질문
이 서버를 프로덕션 환경에서 사용할 수 있나요?
아니요, 현재 Alpha 단계이므로 API가 확정되지 않았으며 예고 없이 릴리스 내용이 변경되거나 식별자가 삭제될 수 있습니다.
에이전트가 셸 히스토리를 어지럽히지 않고 명령어를 실행할 수 있나요?
네, run_command 도구는 기본적으로 히스토리 억제 기능을 사용하여 에이전트가 생성한 입력이 셸 히스토리에 남지 않도록 합니다.