🚀 Tabby-MCP

A Comprehensive MCP Server Plugin for Tabby Terminal

Connect AI assistants to your terminal with full control — 36 MCP tools including SFTP support

English | 中文

---

🚀 Tabby-MCP is a powerful plugin for Tabby Terminal, 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-only server • Comprehensive logging

Safety model (v1.6.3): 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. Network access is restricted to loopback (127.0.0.1), Origin validation is applied to both MCP transports, and 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

curl -fsSL https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.sh | bash

Or download and run:

wget https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.sh
bash install.sh

🪟 Windows (PowerShell)

irm https://raw.githubusercontent.com/GentlemanHu/Tabby-MCP/main/scripts/install.ps1 | iex

Or download and run:

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+.

# Clone
git clone https://github.com/GentlemanHu/Tabby-MCP.git
cd Tabby-MCP

# Build & Install
bash scripts/build-and-install.sh

Or manually:

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:

{
  "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):

{
  "mcpServers": {
    "tabby-mcp-server": {
      "command": "node",
      "args": ["/path/to/Tabby-MCP/scripts/stdio-bridge.js"]
    }
  }
}

VS Code / Other IDEs:

{
  "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
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 only to 127.0.0.1; 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 by @thuanpham582002.

Improvements over the original:

Feature	Original	This Project
MCP Tools	4	35
Tab Management	❌	✅
Profile/SSH	❌	✅
SFTP Support	❌	✅
Stable Session IDs	❌	✅
Streamable HTTP	❌	✅
Init Bug	Has issue	✅ Fixed
Install Script	Manual	✅ One-liner

---

📝 Changelog

v1.6.3-rc.2 (2026-07-29) — prerelease

⚠️ Prerelease, not yet published to npm. Install it from the GitHub prerelease and please report anything that misbehaves on the referenced issues.

Keyboard-interactive authentication has been exercised end to end in a real Tabby session — MFA submission through to the Jumpserver asset menu, on Tabby 1.0.229 and 1.0.235 for macOS. The rc.1 fixes below — dialog focus restoration, live SFTP transfer cancellation, and multi-instance port handover — have not been exercised by hand yet and still need testing.

• Added submit_keyboard_interactive_response for SSH keyboard-interactive authentication, including MFA/TOTP prompts (PR #8, thanks @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 a startup crash on Tabby 1.0.235 where ConfigService.store was not yet available during Angular service construction, which pushed Tabby into third-party-plugin safe mode.
• Tool count is now documented accurately: 36 total (35 normally visible; get_session_environment is optional and disabled by default).

v1.6.3-rc.1 (2026-07-27) — prerelease

• Fixed Issue #9: Pair Programming approval now covers send_input and sensitive SFTP operations; transfer cancellation now stops the underlying transfer.
• Fixed Issue #7: replaced blocking browser dialogs with a non-blocking focus-restoring dialog and made command focus honor the Auto-focus setting.
• Fixed Issue #5: loopback-only bind, startup retry, stale-instance detection, and authenticated same-install port handover.
• 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.

See CHANGELOG.md for the complete version history.

---

🤝 Contributing

See CONTRIBUTING.md for guidelines.

---

📄 License

MIT License - see LICENSE

---

Made with ❤️ by AI and GentlemanHu

⭐ Star this repo if you find it useful!