Terminal MCP Server
MCP server for AI agents to interact with terminal applications. Think Playwright for terminals.
Open source Open in the app JSON README (API)
About
MCP server for AI agents to interact with terminal applications. Think Playwright for terminals.
Details
- Kind
- MCP servers
- Topic
- Developer tools
- Publisher
- aybelatchane
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.3
- Stars
- 19
- Forks
- 5
- Last push
- 2026-01-02T11:04:49Z
- Repository state
- ativo
- Language
- Rust
- License
- MIT
- Added
- 2026-08-29 03:02:28
- Updated
- 2026-08-29 03:02:28
- Origin id
io.github.aybelatchane/mcp-server-terminal
README
# Terminal MCP Server
[](https://www.npmjs.com/package/mcp-server-terminal)
[](https://www.npmjs.com/package/mcp-server-terminal)
[](https://opensource.org/licenses/MIT)
MCP 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/).
## Installation
### Via npm (Recommended)
```bash
npx mcp-server-terminal
```
### Via GitHub Releases
Download pre-built binaries from [Releases](https://github.com/aybelatchane/mcp-server-terminal/releases).
### Build from Source
```bash
git clone https://github.com/aybelatchane/mcp-server-terminal.git
cd mcp-server-terminal
cargo build --release
# Binary: ./target/release/terminal-mcp
```
## Configuration
### Claude
#### Claude Code (CLI)
```bash
claude mcp add terminal -- npx mcp-server-terminal
```
#### Claude Desktop
Add to `~/.claude.json` (macOS/Linux) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### OpenAI Codex
#### Codex CLI
```bash
codex mcp add terminal -- npx mcp-server-terminal
```
#### Codex Configuration File
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.terminal]
command = "npx"
args = ["mcp-server-terminal"]
```
---
### Google Gemini
#### Gemini CLI
```bash
gemini mcp add terminal npx mcp-server-terminal
```
---
### VS Code / GitHub Copilot
VS Code 1.101+ supports MCP. Add to your VS Code settings (`settings.json`):
```json
{
"mcp.servers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### Cursor
Add to `~/.cursor/mcp.json` or `.cursor/mcp.json` in your project:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### Windsurf
Add to `~/.codeium/windsurf/mcp_config.json`:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### Zed
Add to your Zed settings (Preferences → Settings):
```json
{
"context_servers": {
"terminal": {
"command": {
"path": "npx",
"args": ["mcp-server-terminal"]
}
}
}
}
```
---
### Cline (VS Code Extension)
Click MCP Servers icon → Configure → Advanced MCP Settings, then add:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### AWS Bedrock
Add to your Bedrock agent MCP configuration:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"]
}
}
}
```
---
### Other MCP Clients
For any MCP-compatible client, configure the server with:
- **Command**: `npx`
- **Args**: `["mcp-server-terminal"]`
Or if using the binary directly:
- **Command**: `terminal-mcp`
## Usage
Ask your AI agent:
- *"Create a terminal session running htop"*
- *"Take a snapshot of the terminal"*
- *"Press the down arrow key"*
- *"Type 'ls -la' and press Enter"*
## MCP Tools
| Tool | Description |
|------|-------------|
| `terminal_session_create` | Start a terminal session |
| `terminal_session_list` | List active sessions |
| `terminal_session_close` | Close a session |
| `terminal_session_resize` | Resize terminal dimensions |
| `terminal_snapshot` | Capture terminal state with UI elements |
| `terminal_type` | Type text into terminal |
| `terminal_press_key` | Press keys (arrows, F-keys, Ctrl+X) |
| `terminal_click` | Click on detected UI element |
| `terminal_wait_for` | Wait for text, element, or idle state |
| `terminal_read_output` | Read raw terminal output |
## Visual Mode
By default, sessions spawn a visible terminal window (xterm). For headless operation:
```bash
npx mcp-server-terminal --headless
```
Or in your MCP config:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal", "--headless"]
}
}
}
```
### X11 Setup (Linux/WSL)
Visual mode requires X11. Add the DISPLAY environment variable to your MCP config:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"],
"env": {
"DISPLAY": ":0"
}
}
}
}
```
## Logging
Set the `RUST_LOG` environment variable:
```json
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["mcp-server-terminal"],
"env": {
"RUST_LOG": "info"
}
}
}
}
```
Log levels: `error`, `warn`, `info`, `debug`, `trace`
Logs go to stderr (stdout is reserved for MCP protocol).
## Platform Support
| Platform | Architecture | Status | Visual Mode |
|----------|--------------|--------|-------------|
| Linux | x64, arm64 | ✅ Full support | xterm + tmux |
| macOS | x64, arm64 | ✅ Full support | Terminal.app / iTerm2 |
| Windows (WSL) | x64, arm64 | ✅ Full support | xterm + tmux (via X11) |
| Windows (native) | x64 | ⚠️ Headless only | Not supported |
> **Windows users:** Use WSL for full functionality including visual mode.
## License
MIT