How to add Tmux MCP Server to Windsurf

Let AI assistants read, control, and observe your tmux terminal sessions, windows, and panes. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 292★ · stdio · no auth

Windsurf config for Tmux MCP Server

npx -y tmux-mcp

{
  "mcpServers": {
    "tmux-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "tmux-mcp"
      ]
    }
  }
}

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the Tmux MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5Tmux MCP Server's tools become available to Cascade.

Before you start

Node.js
tmux installed and running

What Tmux MCP Server can do in Windsurf

list-sessions

List all active tmux sessions.

find-session

Find a tmux session by name.

list-windows

List windows in a tmux session.

list-panes

List panes in a tmux window.

capture-pane

Capture content from a tmux pane.

create-session

Create a new tmux session.

create-window

Create a new window in a tmux session.

split-pane

Split a tmux pane horizontally or vertically with optional size.

Security

The execute-command tool runs arbitrary shell commands in your tmux panes on your local machine. The README explicitly warns to use it at your own risk. Only enable this server in trusted environments.

Tmux MCP Server + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the Tmux MCP Server config there under the "mcpServers" key and restart the client.

Is Tmux MCP Server safe to use with Windsurf?

How do I install it?

Add the server to your Claude Desktop config with command "npx" and args ["-y", "tmux-mcp"]. No separate install step is required beyond having Node.js and tmux.

Can I use a shell other than bash?

Yes. Pass --shell-type to the server (e.g. "--shell-type=fish"). It defaults to bash. The shell is only needed so the server can correctly read a command's exit status when executing commands.

Is it safe to let the model execute commands?

The execute-command tool runs arbitrary commands in your tmux panes, so it can affect your machine. The README explicitly says to use it at your own risk. Only use it in environments you trust.

View repo Full Tmux MCP Server page