Terminal MCP Server

1# Terminal MCP Server
2 
3[![npm version](https://img.shields.io/npm/v/mcp-server-terminal.svg)](https://www.npmjs.com/package/mcp-server-terminal)
4[![npm downloads](https://img.shields.io/npm/dm/mcp-server-terminal.svg)](https://www.npmjs.com/package/mcp-server-terminal)
5[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
6 
7MCP server enabling AI agents to interact with terminal applications through structured Terminal State Tree representation. Works with any AI assistant that supports the [Model Context Protocol](https://modelcontextprotocol.io/).
8 
9## Installation
10 
11### Via npm (Recommended)
12 
13```bash
14npx mcp-server-terminal
15```
16 
17### Via GitHub Releases
18 
19Download pre-built binaries from [Releases](https://github.com/aybelatchane/mcp-server-terminal/releases).
20 
21### Build from Source
22 
23```bash
24git clone https://github.com/aybelatchane/mcp-server-terminal.git
25cd mcp-server-terminal
26cargo build --release
27# Binary: ./target/release/terminal-mcp
28```
29 
30## Configuration
31 
32### Claude
33 
34#### Claude Code (CLI)
35 
36```bash
37claude mcp add terminal -- npx mcp-server-terminal
38```
39 
40#### Claude Desktop
41 
42Add to `~/.claude.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
43 
44```json
45{
46  "mcpServers": {
47    "terminal": {
48      "command": "npx",
49      "args": ["mcp-server-terminal"]
50    }
51  }
52}
53```
54 
55---
56 
57### OpenAI Codex
58 
59#### Codex CLI
60 
61```bash
62codex mcp add terminal -- npx mcp-server-terminal
63```
64 
65#### Codex Configuration File
66 
67Add to `~/.codex/config.toml`:
68 
69```toml
70[mcp_servers.terminal]
71command = "npx"
72args = ["mcp-server-terminal"]
73```
74 
75---
76 
77### Google Gemini
78 
79#### Gemini CLI
80 
81```bash
82gemini mcp add terminal npx mcp-server-terminal
83```
84 
85---
86 
87### VS Code / GitHub Copilot
88 
89VS Code 1.101+ supports MCP. Add to your VS Code settings (`settings.json`):
90 
91```json
92{
93  "mcp.servers": {
94    "terminal": {
95      "command": "npx",
96      "args": ["mcp-server-terminal"]
97    }
98  }
99}
100```
101 
102---
103 
104### Cursor
105 
106Add to `~/.cursor/mcp.json` or `.cursor/mcp.json` in your project:
107 
108```json
109{
110  "mcpServers": {
111    "terminal": {
112      "command": "npx",
113      "args": ["mcp-server-terminal"]
114    }
115  }
116}
117```
118 
119---
120 
121### Windsurf
122 
123Add to `~/.codeium/windsurf/mcp_config.json`:
124 
125```json
126{
127  "mcpServers": {
128    "terminal": {
129      "command": "npx",
130      "args": ["mcp-server-terminal"]
131    }
132  }
133}
134```
135 
136---
137 
138### Zed
139 
140Add to your Zed settings (Preferences → Settings):
141 
142```json
143{
144  "context_servers": {
145    "terminal": {
146      "command": {
147        "path": "npx",
148        "args": ["mcp-server-terminal"]
149      }
150    }
151  }
152}
153```
154 
155---
156 
157### Cline (VS Code Extension)
158 
159Click MCP Servers icon → Configure → Advanced MCP Settings, then add:
160 
161```json
162{
163  "mcpServers": {
164    "terminal": {
165      "command": "npx",
166      "args": ["mcp-server-terminal"]
167    }
168  }
169}
170```
171 
172---
173 
174### AWS Bedrock
175 
176Add to your Bedrock agent MCP configuration:
177 
178```json
179{
180  "mcpServers": {
181    "terminal": {
182      "command": "npx",
183      "args": ["mcp-server-terminal"]
184    }
185  }
186}
187```
188 
189---
190 
191### Other MCP Clients
192 
193For any MCP-compatible client, configure the server with:
194 
195- **Command**: `npx`
196- **Args**: `["mcp-server-terminal"]`
197 
198Or if using the binary directly:
199 
200- **Command**: `terminal-mcp`
201 
202## Usage
203 
204Ask your AI agent:
205 
206- *"Create a terminal session running htop"*
207- *"Take a snapshot of the terminal"*
208- *"Press the down arrow key"*
209- *"Type 'ls -la' and press Enter"*
210 
211## MCP Tools
212 
213| Tool | Description |
214|------|-------------|
215| `terminal_session_create` | Start a terminal session |
216| `terminal_session_list` | List active sessions |
217| `terminal_session_close` | Close a session |
218| `terminal_session_resize` | Resize terminal dimensions |
219| `terminal_snapshot` | Capture terminal state with UI elements |
220| `terminal_type` | Type text into terminal |
221| `terminal_press_key` | Press keys (arrows, F-keys, Ctrl+X) |
222| `terminal_click` | Click on detected UI element |
223| `terminal_wait_for` | Wait for text, element, or idle state |
224| `terminal_read_output` | Read raw terminal output |
225 
226## Visual Mode
227 
228By default, sessions spawn a visible terminal window (xterm). For headless operation:
229 
230```bash
231npx mcp-server-terminal --headless
232```
233 
234Or in your MCP config:
235 
236```json
237{
238  "mcpServers": {
239    "terminal": {
240      "command": "npx",
241      "args": ["mcp-server-terminal", "--headless"]
242    }
243  }
244}
245```
246 
247### X11 Setup (Linux/WSL)
248 
249Visual mode requires X11. Add the DISPLAY environment variable to your MCP config:
250 
251```json
252{
253  "mcpServers": {
254    "terminal": {
255      "command": "npx",
256      "args": ["mcp-server-terminal"],
257      "env": {
258        "DISPLAY": ":0"
259      }
260    }
261  }
262}
263```
264 
265## Logging
266 
267Set the `RUST_LOG` environment variable:
268 
269```json
270{
271  "mcpServers": {
272    "terminal": {
273      "command": "npx",
274      "args": ["mcp-server-terminal"],
275      "env": {
276        "RUST_LOG": "info"
277      }
278    }
279  }
280}
281```
282 
283Log levels: `error`, `warn`, `info`, `debug`, `trace`
284 
285Logs go to stderr (stdout is reserved for MCP protocol).
286 
287## Platform Support
288 
289| Platform | Architecture | Status | Visual Mode |
290|----------|--------------|--------|-------------|
291| Linux | x64, arm64 | ✅ Full support | xterm + tmux |
292| macOS | x64, arm64 | ✅ Full support | Terminal.app / iTerm2 |
293| Windows (WSL) | x64, arm64 | ✅ Full support | xterm + tmux (via X11) |
294| Windows (native) | x64 | ⚠️ Headless only | Not supported |
295 
296> **Windows users:** Use WSL for full functionality including visual mode.
297 
298## License
299 
300MIT
301