🚀 Tabby-MCP

A Comprehensive MCP Server Plugin for Tabby Terminal

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

🚀 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

Pair programming mode with confirmation dialogs • Comprehensive logging • Safe command execution

📦 Installation

Method 1: Tabby Plugin Manager (Easiest)

Search for tabby-mcp-server directly in Tabby's built-in Plugin Manager:

Open Tabby → Settings → Plugins
Search for tabby-mcp-server
Click Install
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

Restart Tabby
Go to Settings → MCP
Start the MCP server

🔌 Connecting AI Clients

SSE Mode (Cursor / Windsurf)

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Tabby MCP": {
      "type": "sse",
      "url": "http://localhost: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://localhost:3001/mcp`	2025-03-26 (recommended)
Legacy SSE	`http://localhost:3001/sse`	2024-11-05
Health	`http://localhost:3001/health`	-
Info	`http://localhost:3001/info`	-

🛠️ Available Tools

Terminal Control (7)

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)
`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

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`	SSH quick connect

SFTP Operations (12) 🆕

Requires tabby-ssh plugin. If not installed, SFTP tools are disabled automatically.

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	true
Session Tracking	Use stable UUIDs	true
Background Execution	Run without focus	false
SFTP Enabled	Enable SFTP tools	true

🔄 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" enabled with confirmation dialogs for safety.

⚠️ 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	34
Tab Management	❌	✅
Profile/SSH	❌	✅
SFTP Support	❌	✅
Stable Session IDs	❌	✅
Streamable HTTP	❌	✅
Init Bug	Has issue	✅ Fixed
Install Script	Manual	✅ One-liner

📝 Changelog

v1.2.0 (2026-01-24)

🔧 Critical Bug Fixes:

🔴 SFTP Session ID Mismatch - Fixed critical bug where SFTP tools operated on wrong SSH server
- Root cause: SFTP had separate session registry from Terminal, causing ID mismatch
- Fix: SFTP now shares session registry with Terminal tools
- SFTP no longer silently falls back to first SSH tab when sessionId doesn't match
🔴 Local Directory Auto-Creation - SFTP downloads now automatically create missing local directories
🔴 Error Reporting - Fixed misleading "Remote file not found" when local directory was missing

🎨 UI Improvements:

📋 Connection Monitor - Added "Connections" button to settings (always visible)
🛠️ Server Lifecycle - Improved server restart with forced socket cleanup
📊 Session Tracking - Added session metadata with activity history

🔧 Terminal Improvements:

🐚 Heredoc Support - Fixed complex shell commands (Python heredoc) execution
📝 Detailed Logging - Added [findSSHSession] debug logs for troubleshooting

v1.1.6 (2026-01-22)

Improvements:

🎨 Enhanced Settings UI - Redesigned header with compact social links (GitHub, npm)
🔗 Smart Links - All external links now open correctly in default browser
🔢 Auto-versioning - Plugin version is now automatically read from package.json
🧹 Cleaner UI - Optimized layout and removed redundant sections

v1.1.5 (2026-01-22)

New Features:

🌐 Internationalization (i18n) - Settings UI now supports multiple languages
- English (en-US, en-GB)
- Chinese Simplified (zh-CN, zh-TW)
- Auto-follows Tabby's language setting
- Extensible: easily add new languages by adding JSON files

v1.1.4 (2026-01-22)

New Features:

🔄 Background Execution Mode - Run MCP commands without switching terminal focus
- Settings UI with comprehensive risk warnings
- Split pane focus handling for proper pane targeting
🐚 Multi-shell Compatibility - exec_command now supports Fish, Bash, Zsh, and sh
- Auto-detects shell type from terminal buffer patterns
- Shell-specific command wrappers for exit code capture

Bug Fixes:

🔧 Fixed open_profile SSH readiness detection - no longer returns prematurely before SSH is connected
Fixed shell detection for non-bash shells (Fish shell $status vs $?)

v1.1.3 (2026-01-22)

Bug Fixes:

🔧 Fixed open_profile sessionId inconsistency - now returns same sessionId as get_session_list
Fixed SSH connection state detection - ready now correctly reflects overall connection status

Improvements:

Clearer state fields in open_profile response:
- tabReady: Tab/frontend initialized
- sshConnected: SSH connection established (SSH profiles only)
- ready: Overall ready state (for SSH: tabReady AND sshConnected)
Marked all peerDependencies as optional to prevent unnecessary package downloads
Added tabby-ssh to devDependencies for developer build stability

v1.1.2 (2026-01-22)

Optimization:

📦 Reduced npm package size by moving bundled dependencies to devDependencies
All dependencies (express, zod, @modelcontextprotocol/sdk) are now bundled into dist/index.js
Installing from npm/Tabby store no longer downloads unnecessary packages

v1.1.1 (2026-01-21)

Bug Fixes:

🔧 Fixed Streamable HTTP connection leak - connections were not being cleaned up when clients disconnected
Added transport.onclose handler to properly remove closed sessions from tracking
Enhanced SSE stream close logging for better debugging

v1.1.0 (2026-01-20)

Major Fixes:

SFTP tools completely rewritten - Fixed all SFTP tools that were returning "No SSH session found"
Fixed SSH tab detection to properly handle tabs inside SplitTabComponent
Fixed get_terminal_buffer and select_tab returning error when called without parameters
Fixed select_tab tool not finding tabs by tabId (bidirectional lookup)
Fixed quick_connect and open_profile parameter validation issues

Improvements:

All tools now use smart defaults: no parameters = use active session/tab/first SSH session
Updated documentation: tool count corrected to 34 (Terminal 7 + Tab 11 + Profile 4 + SFTP 12)
Added detailed debug logging and better error messages
Added focus_pane and split_tab to documentation
Added Streamable HTTP transport support (protocol 2025-03-26)
Settings: SFTP size limits now use MB instead of bytes
Settings: Updated SFTP notes (removed outdated base64 warning)

🤝 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!

🚀 Tabby-MCP

A Comprehensive MCP Server Plugin for Tabby Terminal

Connect AI assistants to your terminal with full control — 34 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

Pair programming mode with confirmation dialogs • Comprehensive logging • Safe command execution

📦 Installation

Method 1: Tabby Plugin Manager (Easiest)

Search for tabby-mcp-server directly in Tabby's built-in Plugin Manager:

Open Tabby → Settings → Plugins
Search for tabby-mcp-server
Click Install
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

Restart Tabby
Go to Settings → MCP
Start the MCP server

🔌 Connecting AI Clients

SSE Mode (Cursor / Windsurf)

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "Tabby MCP": {
      "type": "sse",
      "url": "http://localhost: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://localhost:3001/mcp`	2025-03-26 (recommended)
Legacy SSE	`http://localhost:3001/sse`	2024-11-05
Health	`http://localhost:3001/health`	-
Info	`http://localhost:3001/info`	-

🛠️ Available Tools

Terminal Control (7)

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)
`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

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`	SSH quick connect

SFTP Operations (12) 🆕

Requires tabby-ssh plugin. If not installed, SFTP tools are disabled automatically.

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	true
Session Tracking	Use stable UUIDs	true
Background Execution	Run without focus	false
SFTP Enabled	Enable SFTP tools	true

🔄 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" enabled with confirmation dialogs for safety.

⚠️ 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	34
Tab Management	❌	✅
Profile/SSH	❌	✅
SFTP Support	❌	✅
Stable Session IDs	❌	✅
Streamable HTTP	❌	✅
Init Bug	Has issue	✅ Fixed
Install Script	Manual	✅ One-liner

📝 Changelog

v1.2.0 (2026-01-24)

🔧 Critical Bug Fixes:

🔴 SFTP Session ID Mismatch - Fixed critical bug where SFTP tools operated on wrong SSH server
- Root cause: SFTP had separate session registry from Terminal, causing ID mismatch
- Fix: SFTP now shares session registry with Terminal tools
- SFTP no longer silently falls back to first SSH tab when sessionId doesn't match
🔴 Local Directory Auto-Creation - SFTP downloads now automatically create missing local directories
🔴 Error Reporting - Fixed misleading "Remote file not found" when local directory was missing

🎨 UI Improvements:

📋 Connection Monitor - Added "Connections" button to settings (always visible)
🛠️ Server Lifecycle - Improved server restart with forced socket cleanup
📊 Session Tracking - Added session metadata with activity history

🔧 Terminal Improvements:

🐚 Heredoc Support - Fixed complex shell commands (Python heredoc) execution
📝 Detailed Logging - Added [findSSHSession] debug logs for troubleshooting

v1.1.6 (2026-01-22)

Improvements:

🎨 Enhanced Settings UI - Redesigned header with compact social links (GitHub, npm)
🔗 Smart Links - All external links now open correctly in default browser
🔢 Auto-versioning - Plugin version is now automatically read from package.json
🧹 Cleaner UI - Optimized layout and removed redundant sections

v1.1.5 (2026-01-22)

New Features:

🌐 Internationalization (i18n) - Settings UI now supports multiple languages
- English (en-US, en-GB)
- Chinese Simplified (zh-CN, zh-TW)
- Auto-follows Tabby's language setting
- Extensible: easily add new languages by adding JSON files

v1.1.4 (2026-01-22)

New Features:

🔄 Background Execution Mode - Run MCP commands without switching terminal focus
- Settings UI with comprehensive risk warnings
- Split pane focus handling for proper pane targeting
🐚 Multi-shell Compatibility - exec_command now supports Fish, Bash, Zsh, and sh
- Auto-detects shell type from terminal buffer patterns
- Shell-specific command wrappers for exit code capture

Bug Fixes:

🔧 Fixed open_profile SSH readiness detection - no longer returns prematurely before SSH is connected
Fixed shell detection for non-bash shells (Fish shell $status vs $?)

v1.1.3 (2026-01-22)

Bug Fixes:

🔧 Fixed open_profile sessionId inconsistency - now returns same sessionId as get_session_list
Fixed SSH connection state detection - ready now correctly reflects overall connection status

Improvements:

Clearer state fields in open_profile response:
- tabReady: Tab/frontend initialized
- sshConnected: SSH connection established (SSH profiles only)
- ready: Overall ready state (for SSH: tabReady AND sshConnected)
Marked all peerDependencies as optional to prevent unnecessary package downloads
Added tabby-ssh to devDependencies for developer build stability

v1.1.2 (2026-01-22)

Optimization:

📦 Reduced npm package size by moving bundled dependencies to devDependencies
All dependencies (express, zod, @modelcontextprotocol/sdk) are now bundled into dist/index.js
Installing from npm/Tabby store no longer downloads unnecessary packages

v1.1.1 (2026-01-21)

Bug Fixes:

🔧 Fixed Streamable HTTP connection leak - connections were not being cleaned up when clients disconnected
Added transport.onclose handler to properly remove closed sessions from tracking
Enhanced SSE stream close logging for better debugging

v1.1.0 (2026-01-20)

Major Fixes:

SFTP tools completely rewritten - Fixed all SFTP tools that were returning "No SSH session found"
Fixed SSH tab detection to properly handle tabs inside SplitTabComponent
Fixed get_terminal_buffer and select_tab returning error when called without parameters
Fixed select_tab tool not finding tabs by tabId (bidirectional lookup)
Fixed quick_connect and open_profile parameter validation issues

Improvements:

All tools now use smart defaults: no parameters = use active session/tab/first SSH session
Updated documentation: tool count corrected to 34 (Terminal 7 + Tab 11 + Profile 4 + SFTP 12)
Added detailed debug logging and better error messages
Added focus_pane and split_tab to documentation
Added Streamable HTTP transport support (protocol 2025-03-26)
Settings: SFTP size limits now use MB instead of bytes
Settings: Updated SFTP notes (removed outdated base64 warning)

🤝 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!