iterm2-mcp 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- iterm2_mcp-0.1.0/.github/workflows/ci.yml +17 -0
- iterm2_mcp-0.1.0/.github/workflows/publish.yml +18 -0
- iterm2_mcp-0.1.0/.gitignore +10 -0
- iterm2_mcp-0.1.0/CLAUDE.md +31 -0
- iterm2_mcp-0.1.0/LICENSE +21 -0
- iterm2_mcp-0.1.0/PKG-INFO +116 -0
- iterm2_mcp-0.1.0/README.md +93 -0
- iterm2_mcp-0.1.0/pyproject.toml +56 -0
- iterm2_mcp-0.1.0/src/iterm2_mcp/__init__.py +5 -0
- iterm2_mcp-0.1.0/src/iterm2_mcp/__main__.py +4 -0
- iterm2_mcp-0.1.0/src/iterm2_mcp/py.typed +0 -0
- iterm2_mcp-0.1.0/src/iterm2_mcp/server.py +432 -0
- iterm2_mcp-0.1.0/uv.lock +906 -0
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
name: CI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches: [main]
|
|
6
|
+
pull_request:
|
|
7
|
+
|
|
8
|
+
jobs:
|
|
9
|
+
lint:
|
|
10
|
+
runs-on: ubuntu-latest
|
|
11
|
+
steps:
|
|
12
|
+
- uses: actions/checkout@v4
|
|
13
|
+
- uses: astral-sh/setup-uv@v6
|
|
14
|
+
- run: uv sync
|
|
15
|
+
- run: uv run ruff check
|
|
16
|
+
- run: uv run ruff format --check
|
|
17
|
+
- run: uv run ty check
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
name: Publish to PyPI
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
release:
|
|
5
|
+
types: [published]
|
|
6
|
+
|
|
7
|
+
permissions:
|
|
8
|
+
id-token: write
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
publish:
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
environment: pypi
|
|
14
|
+
steps:
|
|
15
|
+
- uses: actions/checkout@v4
|
|
16
|
+
- uses: astral-sh/setup-uv@v6
|
|
17
|
+
- run: uv build
|
|
18
|
+
- uses: pypa/gh-action-pypi-publish@release/v1
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
## Project
|
|
4
|
+
|
|
5
|
+
MCP server exposing iTerm2 control via the iTerm2 Python API. Single-module server (`src/iterm2_mcp/server.py`) using `FastMCP`.
|
|
6
|
+
|
|
7
|
+
## Commands
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
uv sync # Install dependencies
|
|
11
|
+
uv run ruff check # Lint
|
|
12
|
+
uv run ruff format # Format
|
|
13
|
+
uv run ty check # Type check
|
|
14
|
+
uv run iterm2-mcp # Run the server locally
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Code style
|
|
18
|
+
|
|
19
|
+
- **Ruff** for linting and formatting: line length 100, rules `E`, `F`, `I`, `UP`, `B`
|
|
20
|
+
- **ty** for type checking, targeting Python 3.12
|
|
21
|
+
- Type hints on all function signatures
|
|
22
|
+
- Sphinx-style `:param` docstrings — document the "why", not the "what"
|
|
23
|
+
- Comments above the code they describe, not at end of line
|
|
24
|
+
- Imports: stdlib first, then third-party, then local
|
|
25
|
+
|
|
26
|
+
## Architecture
|
|
27
|
+
|
|
28
|
+
- All tools are async functions decorated with `@mcp.tool()` in `server.py`
|
|
29
|
+
- A single `iterm2.Connection` is created lazily and shared via `_connection_singleton()`
|
|
30
|
+
- `_session(session_id)` resolves a session by ID or falls back to the active session — most tools accept an optional `session_id`
|
|
31
|
+
- `run_command` uses `iterm2.PromptMonitor` for real completion detection (requires shell integration)
|
iterm2_mcp-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Loren Carvalho
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: iterm2-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server that gives Claude full control over iTerm2 via the iTerm2 Python API.
|
|
5
|
+
Project-URL: Homepage, https://github.com/lorencarvalho/iterm2-mcp
|
|
6
|
+
Project-URL: Repository, https://github.com/lorencarvalho/iterm2-mcp
|
|
7
|
+
Author: Loren Carvalho
|
|
8
|
+
License: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
18
|
+
Classifier: Topic :: Software Development :: Libraries
|
|
19
|
+
Requires-Python: >=3.10
|
|
20
|
+
Requires-Dist: iterm2>=2.0
|
|
21
|
+
Requires-Dist: mcp>=1.0.0
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# iterm2-mcp
|
|
25
|
+
|
|
26
|
+
An MCP server that provides full control over iTerm2.
|
|
27
|
+
|
|
28
|
+
## Prerequisites
|
|
29
|
+
|
|
30
|
+
1. iTerm2 running on macOS.
|
|
31
|
+
2. **Preferences > General > Magic > "Enable Python API"** must be checked.
|
|
32
|
+
3. Install iTerm2 [shell integration](https://iterm2.com/documentation-shell-integration.html)
|
|
33
|
+
in your shell. `run_command` and session variables like `path`/`jobName` depend on it.
|
|
34
|
+
Without it, `run_command` falls back to its timeout.
|
|
35
|
+
|
|
36
|
+
The first time the server connects, iTerm2 will prompt you to approve the binary. Approve once; subsequent launches are automatic.
|
|
37
|
+
|
|
38
|
+
## Install
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
uv tool install iterm2-mcp
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
Or from source:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
git clone https://github.com/lorencarvalho/iterm2-mcp.git
|
|
48
|
+
cd iterm2-mcp
|
|
49
|
+
uv sync
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Register with Claude
|
|
53
|
+
|
|
54
|
+
**Claude Code:**
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
claude mcp add iterm2 -- uvx iterm2-mcp
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
61
|
+
|
|
62
|
+
```json
|
|
63
|
+
{
|
|
64
|
+
"mcpServers": {
|
|
65
|
+
"iterm2": {
|
|
66
|
+
"command": "uvx",
|
|
67
|
+
"args": ["iterm2-mcp"]
|
|
68
|
+
}
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Security
|
|
74
|
+
|
|
75
|
+
This server can type into terminals, run commands, and close sessions — anything
|
|
76
|
+
you can do in iTerm2. Only connect it to MCP clients you trust. It has no
|
|
77
|
+
sandboxing beyond what iTerm2 itself provides.
|
|
78
|
+
|
|
79
|
+
## Tools
|
|
80
|
+
|
|
81
|
+
Most tools accept an optional `session_id` — omit it to target the currently active
|
|
82
|
+
session.
|
|
83
|
+
|
|
84
|
+
| Tool | Purpose |
|
|
85
|
+
| --- | --- |
|
|
86
|
+
| `list_sessions` | Tree of windows/tabs/sessions with IDs |
|
|
87
|
+
| `get_active_session` | ID and name of the focused session |
|
|
88
|
+
| `focus_session` | Bring a session to the foreground |
|
|
89
|
+
| `write_to_terminal` | Send text (optionally with newline) |
|
|
90
|
+
| `send_control_character` | Send Ctrl-C, Ctrl-D, Ctrl-Z, ESC, etc. |
|
|
91
|
+
| `send_escape_sequence` | Send a raw ANSI escape (e.g. `\x1b[2J`) |
|
|
92
|
+
| `read_screen` | Read the visible screen as plain text |
|
|
93
|
+
| `get_cursor_position` | Current cursor `(x, y)` |
|
|
94
|
+
| `run_command` | Send a command and wait for `COMMAND_END` |
|
|
95
|
+
| `create_window` | Open a new iTerm2 window |
|
|
96
|
+
| `create_tab` | Open a new tab |
|
|
97
|
+
| `split_pane` | Split a pane horizontally or vertically |
|
|
98
|
+
| `close_session` | Close a specific session |
|
|
99
|
+
| `set_session_name` | Rename a session |
|
|
100
|
+
| `set_badge` | Set the iTerm2 badge text |
|
|
101
|
+
| `clear_buffer` | Clear screen and scrollback |
|
|
102
|
+
| `list_profiles` | Enumerate iTerm2 profiles |
|
|
103
|
+
| `get_variable` | Read an iTerm2 session variable |
|
|
104
|
+
|
|
105
|
+
## Development
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
uv sync
|
|
109
|
+
uv run ruff check
|
|
110
|
+
uv run ruff format
|
|
111
|
+
uv run ty check
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
## License
|
|
115
|
+
|
|
116
|
+
MIT
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
# iterm2-mcp
|
|
2
|
+
|
|
3
|
+
An MCP server that provides full control over iTerm2.
|
|
4
|
+
|
|
5
|
+
## Prerequisites
|
|
6
|
+
|
|
7
|
+
1. iTerm2 running on macOS.
|
|
8
|
+
2. **Preferences > General > Magic > "Enable Python API"** must be checked.
|
|
9
|
+
3. Install iTerm2 [shell integration](https://iterm2.com/documentation-shell-integration.html)
|
|
10
|
+
in your shell. `run_command` and session variables like `path`/`jobName` depend on it.
|
|
11
|
+
Without it, `run_command` falls back to its timeout.
|
|
12
|
+
|
|
13
|
+
The first time the server connects, iTerm2 will prompt you to approve the binary. Approve once; subsequent launches are automatic.
|
|
14
|
+
|
|
15
|
+
## Install
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
uv tool install iterm2-mcp
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Or from source:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
git clone https://github.com/lorencarvalho/iterm2-mcp.git
|
|
25
|
+
cd iterm2-mcp
|
|
26
|
+
uv sync
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Register with Claude
|
|
30
|
+
|
|
31
|
+
**Claude Code:**
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
claude mcp add iterm2 -- uvx iterm2-mcp
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
|
|
38
|
+
|
|
39
|
+
```json
|
|
40
|
+
{
|
|
41
|
+
"mcpServers": {
|
|
42
|
+
"iterm2": {
|
|
43
|
+
"command": "uvx",
|
|
44
|
+
"args": ["iterm2-mcp"]
|
|
45
|
+
}
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
## Security
|
|
51
|
+
|
|
52
|
+
This server can type into terminals, run commands, and close sessions — anything
|
|
53
|
+
you can do in iTerm2. Only connect it to MCP clients you trust. It has no
|
|
54
|
+
sandboxing beyond what iTerm2 itself provides.
|
|
55
|
+
|
|
56
|
+
## Tools
|
|
57
|
+
|
|
58
|
+
Most tools accept an optional `session_id` — omit it to target the currently active
|
|
59
|
+
session.
|
|
60
|
+
|
|
61
|
+
| Tool | Purpose |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `list_sessions` | Tree of windows/tabs/sessions with IDs |
|
|
64
|
+
| `get_active_session` | ID and name of the focused session |
|
|
65
|
+
| `focus_session` | Bring a session to the foreground |
|
|
66
|
+
| `write_to_terminal` | Send text (optionally with newline) |
|
|
67
|
+
| `send_control_character` | Send Ctrl-C, Ctrl-D, Ctrl-Z, ESC, etc. |
|
|
68
|
+
| `send_escape_sequence` | Send a raw ANSI escape (e.g. `\x1b[2J`) |
|
|
69
|
+
| `read_screen` | Read the visible screen as plain text |
|
|
70
|
+
| `get_cursor_position` | Current cursor `(x, y)` |
|
|
71
|
+
| `run_command` | Send a command and wait for `COMMAND_END` |
|
|
72
|
+
| `create_window` | Open a new iTerm2 window |
|
|
73
|
+
| `create_tab` | Open a new tab |
|
|
74
|
+
| `split_pane` | Split a pane horizontally or vertically |
|
|
75
|
+
| `close_session` | Close a specific session |
|
|
76
|
+
| `set_session_name` | Rename a session |
|
|
77
|
+
| `set_badge` | Set the iTerm2 badge text |
|
|
78
|
+
| `clear_buffer` | Clear screen and scrollback |
|
|
79
|
+
| `list_profiles` | Enumerate iTerm2 profiles |
|
|
80
|
+
| `get_variable` | Read an iTerm2 session variable |
|
|
81
|
+
|
|
82
|
+
## Development
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
uv sync
|
|
86
|
+
uv run ruff check
|
|
87
|
+
uv run ruff format
|
|
88
|
+
uv run ty check
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
## License
|
|
92
|
+
|
|
93
|
+
MIT
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "iterm2-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server that gives Claude full control over iTerm2 via the iTerm2 Python API."
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = { text = "MIT" }
|
|
12
|
+
authors = [{ name = "Loren Carvalho" }]
|
|
13
|
+
classifiers = [
|
|
14
|
+
"Development Status :: 4 - Beta",
|
|
15
|
+
"Intended Audience :: Developers",
|
|
16
|
+
"License :: OSI Approved :: MIT License",
|
|
17
|
+
"Programming Language :: Python :: 3",
|
|
18
|
+
"Programming Language :: Python :: 3.10",
|
|
19
|
+
"Programming Language :: Python :: 3.11",
|
|
20
|
+
"Programming Language :: Python :: 3.12",
|
|
21
|
+
"Programming Language :: Python :: 3.13",
|
|
22
|
+
"Topic :: Software Development :: Libraries",
|
|
23
|
+
]
|
|
24
|
+
dependencies = [
|
|
25
|
+
"mcp>=1.0.0",
|
|
26
|
+
"iterm2>=2.0",
|
|
27
|
+
]
|
|
28
|
+
|
|
29
|
+
[project.urls]
|
|
30
|
+
Homepage = "https://github.com/lorencarvalho/iterm2-mcp"
|
|
31
|
+
Repository = "https://github.com/lorencarvalho/iterm2-mcp"
|
|
32
|
+
|
|
33
|
+
[project.scripts]
|
|
34
|
+
iterm2-mcp = "iterm2_mcp.server:main"
|
|
35
|
+
|
|
36
|
+
[tool.hatch.build.targets.wheel]
|
|
37
|
+
packages = ["src/iterm2_mcp"]
|
|
38
|
+
|
|
39
|
+
[dependency-groups]
|
|
40
|
+
dev = [
|
|
41
|
+
"ty",
|
|
42
|
+
"ruff",
|
|
43
|
+
]
|
|
44
|
+
|
|
45
|
+
[tool.ty.environment]
|
|
46
|
+
python-version = "3.12"
|
|
47
|
+
|
|
48
|
+
[tool.ty.src]
|
|
49
|
+
include = ["src/**/*.py"]
|
|
50
|
+
|
|
51
|
+
[tool.ruff]
|
|
52
|
+
line-length = 100
|
|
53
|
+
target-version = "py310"
|
|
54
|
+
|
|
55
|
+
[tool.ruff.lint]
|
|
56
|
+
select = ["E", "F", "I", "UP", "B"]
|
|
File without changes
|