🚀 Tabby-MCP

A Comprehensive MCP Server Plugin for Tabby Terminal

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

Safety model (v1.6.3): Pair Programming Mode gates exec_command, send_input, and sensitive SFTP operations with a non-blocking approval dialog that automatically rejects after two minutes. 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.

Related MCP server: Terminally MCP

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

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

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

🛠️ Available Tools

Terminal Control (8)

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)

Profile Management (4)

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:

File Transfer (supports sync/async):

Transfer Modes: sync=true (default) waits for completion. sync=false returns immediately with transferId.

Size Limits: Configurable in Settings → MCP → SFTP.

⚙️ Configuration

🔄 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

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:

📝 Changelog

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

⚠️ Prerelease, not yet published to npm. These fixes are verified by static analysis, a typecheck, smoke regression checks, and a production build — but not by a manual run inside a real Tabby/Electron session. Dialog focus restoration, live SFTP transfer cancellation, and multi-instance port handover in particular still need hands-on testing. Install it from the GitHub prerelease and please report anything that misbehaves on the referenced issues.

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

• Tool count is now documented accurately: 35 total (34 normally visible; get_session_environment is optional and disabled by default).

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!