Metadata-Version: 2.4
Name: libtmux-mcp
Version: 0.1.0a5
Summary: MCP server for tmux, powered by libtmux
Project-URL: Bug Tracker, https://github.com/tmux-python/libtmux-mcp/issues
Project-URL: Documentation, https://libtmux-mcp.git-pull.com
Project-URL: Repository, https://github.com/tmux-python/libtmux-mcp
Project-URL: Changes, https://github.com/tmux-python/libtmux-mcp/blob/master/CHANGES
Author-email: Tony Narlock <tony@git-pull.com>
License: MIT
License-File: LICENSE
Keywords: ai,mcp,model-context-protocol,terminal,tmux
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Classifier: Typing :: Typed
Requires-Python: <4.0,>=3.10
Requires-Dist: fastmcp<4.0.0,>=3.2.4
Requires-Dist: libtmux<1.0,>=0.55.1
Description-Content-Type: text/markdown

# libtmux-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server for [tmux](https://github.com/tmux/tmux), built on [libtmux](https://libtmux.git-pull.com).

[![Python Version](https://img.shields.io/pypi/pyversions/libtmux-mcp.svg)](https://pypi.org/project/libtmux-mcp/)
[![PyPI Version](https://img.shields.io/pypi/v/libtmux-mcp.svg)](https://pypi.org/project/libtmux-mcp/)
[![License](https://img.shields.io/github/license/tmux-python/libtmux-mcp.svg)](https://github.com/tmux-python/libtmux-mcp/blob/master/LICENSE)

> [!WARNING]
> **Pre-alpha.** APIs may change. Contributions and feedback welcome.

Give your AI agent hands inside the terminal — create sessions, run commands, read output, orchestrate panes.

## Tools

| Module | Tools |
|--------|-------|
| **Server** | `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
| **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** | `send_keys`, `paste_text`, `capture_pane`, `snapshot_pane`, `search_panes`, `get_pane_info`, `wait_for_text`, `wait_for_content_change`, `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` |

## Quickstart

**Requirements:** Python 3.10+, tmux on `$PATH`.

Install and run:

```bash
uvx libtmux-mcp
```

### Claude Code

```bash
claude mcp add tmux -- uvx libtmux-mcp
```

### Codex CLI

```bash
codex mcp add tmux -- uvx libtmux-mcp
```

### Gemini CLI

```bash
gemini mcp add tmux uvx -- libtmux-mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tmux": {
      "command": "uvx",
      "args": ["libtmux-mcp"]
    }
  }
}
```

More clients and JSON config: [client setup docs](https://libtmux-mcp.git-pull.com/clients/)

## What it feels like

> **You:** Create a session called "api" and run `pytest tests/api/ -x` in it.
>
> **Agent:** Created session `api` with window `tests`. Running pytest now.
> Here's the output — 14 passed, 2 failed. The failures are in
> `test_auth.py::test_token_refresh` and `test_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.

## Documentation

Full docs, guides, and tool reference: **[libtmux-mcp.git-pull.com](https://libtmux-mcp.git-pull.com)**

## Development

Clone and install:

```bash
git clone https://github.com/tmux-python/libtmux-mcp.git
```

```bash
cd libtmux-mcp
```

```bash
uv sync --dev
```

Run the server locally:

```bash
uv run libtmux-mcp
```

Run tests:

```bash
uv run pytest
```

## Related projects

- [libtmux](https://libtmux.git-pull.com) — Python API for tmux
- [tmuxp](https://tmuxp.git-pull.com) — tmux session manager
- [The Tao of tmux](https://leanpub.com/the-tao-of-tmux) — the book

## License

MIT
