mcp-ssh-wingman

MCP SSH Wingman provides a read-only interface to a Unix tmux session. It exposes tools that let an AI observe the current terminal content, retrieve scrollback history, and obtain terminal metadata such as dimensions and current working directory without executing any commands. You can connect clients like Claude Desktop or Gemini CLI to this MCP server and use the available tools to inspect the session content safely. The server is intended for read-only observation, making it suitable for AI-assisted debugging and contextual analysis of terminal activity.

To use the server, first start the container (or run the binary if you have it available). Once running, you can configure Claude Desktop or Gemini CLI to point at the MCP server using the provided command and session name. The available MCP tools are: read_terminal (gets the current terminal content), read_scrollback (fetches scrollback history with a configurable number of lines), and get_terminal_info (returns information about the terminal such as size and current path). Through MCP resources, you can access terminal://current and terminal://info as well.

Prerequisites:

• tmux installed on the host system
• Docker installed (if using the provided Docker image) or build from source if you prefer a native build

Option A: Run via Docker (recommended)

1. Ensure Docker is running on your machine.
2. Pull and run the image: docker run -i conallob/mcp-ssh-wingman
3. The server should start and expose itself according to its defaults. Use the MCP client to connect to the running server.

Option B: Build from source (if you have the source and toolchain)

1. Install Go and any required build dependencies.
2. Clone the repository and navigate to the project directory.
3. Build the binary (check project docs for exact build command).
4. Run the resulting binary directly.

Prerequisites recap:

• tmux (for session management)
• Optional: Go 1.21+ if building from source

Environment considerations:

• The server operates on local tmux sessions and does not issue any keystrokes or commands to the terminal.
• It is read-only by design; ensure that clients respect the MCP tools and do not attempt to trigger commands.
• If using Claude Desktop or Gemini CLI, ensure the path to the binary/image and the session name match between the MCP server configuration and the client configuration.

Common issues:

• tmux not installed or not in PATH: install tmux and retry.
• Docker image not found or not running: verify image name and that Docker is pulling/running correctly.
• Session naming mismatches: ensure the session name used by the server matches what clients expect.