# π Tabby-MCP
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://tabby.sh/)
[](https://modelcontextprotocol.io/)
[](https://github.com/GentlemanHu/Tabby-MCP/releases)
[](https://www.npmjs.com/package/tabby-mcp-server)
[](https://www.npmjs.com/package/tabby-mcp-server)
[](#-about-this-project)
[](#%EF%B8%8F-platform-support)
**A Comprehensive MCP Server Plugin for Tabby Terminal**
*Connect AI assistants to your terminal with full control β 36 MCP tools including SFTP support*
[English](README.md) | [δΈζ](README_CN.md)
---
> π **Tabby-MCP** is a powerful plugin for [Tabby Terminal](https://github.com/eugeny/tabby), bridging the gap between AI agents and your terminal environment. It provides a standardized MCP interface for AI to execute commands, manage tabs, and handle file operations securely.
>
> *Give your AI hands to work with.*
---
## β¨ Features
π₯οΈ Terminal Control
- Execute commands with output capture
- Stable session IDs (v1.1+)
- Send interactive input (vim, less, top)
- Read terminal buffer content
- Abort/monitor running commands
|
π Tab Management
- Create/Close/Duplicate tabs
- Split panes (horizontal/vertical)
- Navigate between tabs
- Move tabs left/right
- Reopen closed tabs
|
π Profile & SSH
- List all terminal profiles
- Open new tabs with profiles
- SSH quick connect
- Profile selector dialog
|
π SFTP Operations (v1.1+)
- List/read/write remote files
- Create/delete directories
- Rename/move files
- (Requires tabby-ssh)
|
π Security Features
Non-blocking confirmation dialogs for commands, raw input, and sensitive SFTP operations β’ Loopback by default β’ Comprehensive logging
> **Safety model (v1.7.2):** Pair Programming Mode gates `exec_command`, `send_input`, keyboard-interactive authentication responses, and sensitive SFTP operations with a non-blocking approval dialog that automatically rejects after two minutes. Authentication response values are never shown in confirmation details. The dialog restores terminal focus to avoid Electron/xterm keyboard and IME issues. Read-only transfer-status tools and emergency `abort_command` remain available without approval. The server binds to `127.0.0.1` unless you change Listen address. Host and Origin checks still reject DNS names. The direct tool API is disabled by default.
---
## π¦ Installation
### Method 1: Tabby Plugin Manager (Easiest)
Search for `tabby-mcp-server` directly in Tabby's built-in Plugin Manager:
1. Open Tabby β **Settings** β **Plugins**
2. Search for `tabby-mcp-server`
3. Click **Install**
4. Restart Tabby
---
### Method 2: Quick Install Script
**No Node.js required!** Downloads pre-built release from GitHub.
π macOS / π§ Linux
```bash
curl -fsSL https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.sh | bash
```
Or download and run:
```bash
wget https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.sh
bash install.sh
```
πͺ Windows (PowerShell)
```powershell
irm https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.ps1 | iex
```
Or download and run:
```powershell
Invoke-WebRequest -Uri https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.ps1 -OutFile install.ps1
.\install.ps1
```
---
### Method 3: Build from Source
Requires **Node.js 18+**.
```bash
# Clone
git clone https://github.com/GentlemanHu/Tabby-MCP.git
cd Tabby-MCP
# Build & Install
bash scripts/build-and-install.sh
```
Or manually:
```bash
npm install --legacy-peer-deps
npm run build
# Then copy dist/ and package.json to Tabby plugins folder
```
---
### π After Installation
1. **Restart Tabby**
2. Go to **Settings β MCP**
3. Start the MCP server
---
## π Connecting AI Clients
### Streamable HTTP Mode (Cursor / Windsurf / Cline)
Add to `~/.cursor/mcp.json`:
```json
{
"mcpServers": {
"Tabby MCP": {
"type": "streamable_http",
"url": "http://127.0.0.1:3001/mcp"
}
}
}
```
### STDIO Mode (Claude Desktop / VS Code)
For clients that don't support SSE, use the STDIO bridge:
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"tabby-mcp-server": {
"command": "node",
"args": ["/path/to/Tabby-MCP/scripts/stdio-bridge.js"]
}
}
}
```
**VS Code / Other IDEs:**
```json
{
"mcp": {
"servers": {
"tabby-mcp-server": {
"type": "stdio",
"command": "node",
"args": ["scripts/stdio-bridge.js"],
"cwd": "/path/to/Tabby-MCP"
}
}
}
}
```
> **Note**: STDIO mode requires Node.js installed. The bridge script connects to the SSE server running in Tabby.
### Endpoints
| Endpoint | URL | Protocol |
|----------|-----|----------|
| Streamable HTTP | `http://127.0.0.1:3001/mcp` | 2025-03-26 (recommended) |
| Legacy SSE | `http://127.0.0.1:3001/sse` | 2024-11-05 |
| Health | `http://127.0.0.1:3001/health` | - |
| Info | `http://127.0.0.1:3001/info` | - |
---
## π οΈ Available Tools
### Terminal Control (9)
| Tool | Description |
|------|-------------|
| `get_session_list` | List all terminal sessions with **stable UUIDs** and metadata |
| `exec_command` | Execute command with flexible session targeting |
| `send_input` | Send interactive input (Ctrl+C, etc) |
| `submit_keyboard_interactive_response` | Submit MFA, password, or other SSH keyboard-interactive responses |
| `get_terminal_buffer` | Read terminal buffer (defaults to active session) |
| `abort_command` | Abort running command |
| `get_command_status` | Monitor active commands |
| `focus_pane` | Focus a specific pane in split view |
| `get_session_environment` | Detect shell/REPL context (optional; disabled by default) |
> **New in v1.1**: All terminal tools now support flexible session targeting:
> - `sessionId` (stable UUID, recommended)
> - `tabIndex` (legacy, may change)
> - `title` (partial match)
> - `profileName` (partial match)
> - No parameters = use active session
### Tab Management (11)
| Tool | Description |
|------|-------------|
| `list_tabs` | List all open tabs with **stable IDs** |
| `select_tab` | Focus a specific tab (defaults to active) |
| `close_tab` | Close a tab |
| `close_all_tabs` | Close all tabs |
| `duplicate_tab` | Duplicate a tab |
| `next_tab` / `previous_tab` | Navigate tabs |
| `move_tab_left` / `move_tab_right` | Reorder tabs |
| `reopen_last_tab` | Reopen closed tab |
| `split_tab` | Split current tab (horizontal/vertical) |
### Profile Management (4)
| Tool | Description |
|------|-------------|
| `list_profiles` | List terminal profiles |
| `open_profile` | Open tab with profile |
| `show_profile_selector` | Show profile dialog |
| `quick_connect` | Smart quick connect (SSH/telnet/socket/serial) |
### SFTP Operations (12) π
> Requires `tabby-ssh`. If it is not installedβor SFTP is disabled in Settingsβall 12 SFTP tools are omitted for new MCP sessions. With Pair Programming confirmation enabled, directory listing, metadata reads, file reads/writes, transfers, deletes, renames, directory creation, and transfer cancellation require approval.
**Basic Operations:**
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `sftp_list_files` | List remote directory | `path` |
| `sftp_read_file` | Read remote file (text) | `path` |
| `sftp_write_file` | Write text to remote file | `path`, `content` |
| `sftp_mkdir` | Create remote directory | `path` |
| `sftp_delete` | Delete remote file/directory | `path` |
| `sftp_rename` | Rename/move remote file | `sourcePath`, `destPath` |
| `sftp_stat` | Get file/directory info | `path` |
**File Transfer (supports sync/async):**
| Tool | Description | Key Parameters |
|------|-------------|----------------|
| `sftp_upload` | Upload local file β remote | `localPath`, `remotePath`, `sync` |
| `sftp_download` | Download remote β local file | `remotePath`, `localPath`, `sync` |
| `sftp_get_transfer_status` | Query transfer progress | `transferId` |
| `sftp_list_transfers` | List all transfers | `status` (filter) |
| `sftp_cancel_transfer` | Cancel active transfer | `transferId` |
> **Transfer Modes**: `sync=true` (default) waits for completion. `sync=false` returns immediately with `transferId`.
>
> **Size Limits**: Configurable in Settings β MCP β SFTP.
---
## βοΈ Configuration
| Setting | Description | Default |
|---------|-------------|---------|
| Port | MCP server port | 3001 |
| Listen address | Bind address. `0.0.0.0` exposes every interface for WSL; DNS hostnames stay rejected | 127.0.0.1 |
| Start on Boot | Auto-start server | true |
| Pair Programming | Confirm commands, raw input, and sensitive SFTP operations | true |
| Confirm SFTP Operations | Apply the approval dialog to sensitive SFTP operations (`send_input` always follows command confirmation) | true |
| Session Tracking | Use stable UUIDs | true |
| Background Execution | Run without focus | false |
| SFTP Enabled | Enable SFTP tools | true |
| Environment Detection | Expose `get_session_environment` | false |
| Direct Tool API | Enable compatibility endpoint `/api/tool/:name` (manual config only) | false |
---
## π Background Execution Mode
Enable this mode to allow MCP commands to run **without switching focus** to the terminal. This lets you continue working on other tabs while AI executes commands in the background.
**Settings β MCP β Background Execution**
> β οΈ **Risks:**
> - You won't see commands executing in real-time
> - If you type in the target terminal while AI is running, input will conflict
> - For split panes, commands go to the `sessionId` target, not the focused pane
> - Dangerous commands could run without you noticing
> β
**Recommended:** Keep Pair Programming Mode, confirmation dialogs, and file-operation confirmation enabled. The server binds to `127.0.0.1` unless Listen address is changed; the direct `/api/tool/:name` compatibility API is disabled by default.
---
## β οΈ Platform Support
| Platform | Status | Notes |
|----------|--------|-------|
| macOS | β
**Tested** | Fully functional |
| Windows | β οΈ Untested | Should work β please report issues |
| Linux | β οΈ Untested | Should work β please report issues |
> **Note**: This plugin has been developed and tested on macOS. Windows and Linux support should work but is unverified. Community testing and feedback welcome!
---
## π€ About This Project
### π¨ 95%+ AI Generated
This project was created almost entirely by AI (Claude/Gemini) through pair programming.
The human's role was primarily to provide requirements and test the results.
### Acknowledgments
This project builds upon the work of [tabby-mcp-server](https://github.com/thuanpham582002/tabby-mcp-server) by [@thuanpham582002](https://github.com/thuanpham582002).
**Improvements over the original:**
| Feature | Original | This Project |
|---------|----------|--------------|
| MCP Tools | 4 | **36** |
| Tab Management | β | β
|
| Profile/SSH | β | β
|
| SFTP Support | β | β
|
| Stable Session IDs | β | β
|
| Streamable HTTP | β | β
|
| Init Bug | Has issue | β
Fixed |
| Install Script | Manual | β
One-liner |
---
## π Changelog
### v1.7.2 (2026-10-10)
- Listen address is configurable (default `127.0.0.1`). Set `0.0.0.0` when a WSL or other-interface client must connect. Non-loopback binds warn that the server has no login.
- The settings tab checks npm for a newer release and installs it through Tabby's built-in plugin installer.
- Header actions use real icons instead of emoji.
- View Logs shows the log in the settings page and opens Tabby's developer tools on macOS, Windows, and Linux.
### v1.7.1 (2026-09-15)
Published to [GitHub](https://github.com/GentlemanHu/Tabby-MCP/releases/tag/v1.7.1) and npm (`tabby-mcp-server@1.7.1`).
- Fixed [Issue #10](https://github.com/GentlemanHu/Tabby-MCP/issues/10) / [Issue #11](https://github.com/GentlemanHu/Tabby-MCP/issues/11): pending approvals attract OS attention again after 1.7.0 replaced native `confirm()`. macOS bounces the Dock without stealing focus; Windows/Linux flash the taskbar and bring the window forward. The non-blocking dialog and IME/keyboard fix from #7 are unchanged.
### v1.7.0 (2026-09-09)
Stable release of the 1.6.3-rc.1 / 1.6.3-rc.2 line. Published to [GitHub](https://github.com/GentlemanHu/Tabby-MCP/releases/tag/v1.7.0) and npm (`tabby-mcp-server@1.7.0`).
- Added `submit_keyboard_interactive_response` for SSH keyboard-interactive authentication, including MFA/TOTP prompts ([PR #8](https://github.com/GentlemanHu/Tabby-MCP/pull/8), thanks [@plane636](https://github.com/plane636)). `send_input` writes to the terminal PTY and cannot reach Tabby's authentication panel. Pair Programming confirmation shows only the response count, never credential values.
- `get_session_list` now reports `sshConnected`, `keyboardInteractivePending`, and non-secret prompt metadata.
- Fixed [Issue #9](https://github.com/GentlemanHu/Tabby-MCP/issues/9): Pair Programming approval now covers `send_input`, keyboard-interactive responses, and sensitive SFTP operations; transfer cancellation now stops the underlying transfer.
- Fixed [Issue #7](https://github.com/GentlemanHu/Tabby-MCP/issues/7): replaced blocking browser dialogs with a non-blocking focus-restoring dialog and made command focus honor the Auto-focus setting.
- Fixed [Issue #5](https://github.com/GentlemanHu/Tabby-MCP/issues/5): loopback-only bind, startup retry, stale-instance detection, and authenticated same-install port handover.
- Fixed a startup crash on Tabby 1.0.235 where `ConfigService.store` was not yet available during Angular service construction.
- Fixed Legacy SSE JSON body handling for SDK 1.25.2, session cleanup, stale Streamable HTTP session handling, Origin validation, fish active environment probes, SFTP locator consistency, and STDIO reconnect/framing behavior.
- Pinned `@modelcontextprotocol/sdk` to 1.25.2, committed `package-lock.json`, and added typecheck/smoke/build quality gates.
- 36 MCP tools (35 normally visible; `get_session_environment` is optional and disabled by default).
See [CHANGELOG.md](CHANGELOG.md) for the complete version history.
---
## π€ Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
---
## π License
MIT License - see [LICENSE](LICENSE)
---
Made with β€οΈ by AI and [GentlemanHu](https://github.com/GentlemanHu)
β **Star this repo if you find it useful!**