PuTTY MCP Server

Minimal Model Context Protocol server for interacting with already opened PuTTY windows on Windows.

The server exposes 5 tools: list windows, read terminal output, send commands, clear scrollback, and chunked file upload.

Tools

Tool	Description
putty_list_windows	List visible PuTTY windows with title and PID
putty_read_window	Read full text (screen + scrollback) from a selected PuTTY window
putty_send_command	Send text to a selected PuTTY window (optionally with Enter)
putty_clear_window	Clear scrollback/history in a selected PuTTY window
putty_upload_text	Upload long text/data to a remote path via short printf chunks

Window selection

When several PuTTY windows are open, pass one of these selectors to putty_read_window, putty_send_command, and putty_clear_window:

Parameter	Description
process_id	PID from putty_list_windows (most reliable)
host	Substring matched against window title (case-insensitive)
title_substring	Same as host; alternative name for title matching

If exactly one PuTTY window is open, the selector is optional.

Tool parameters

putty_send_command

• command (required) — text to send
• append_newline (default: true) — append Enter after the command

putty_upload_text

• content (required) — payload to write remotely
• remote_path (required) — destination path on the remote host
• encoding — shell (default, UTF-8 text) or hex (binary-safe, no remote base64)
• chunk_size — optional override; keep resulting shell lines under ~480 chars
• verify (default: true) — check remote size with wc -c

putty_read_window, putty_clear_window, putty_send_command, putty_upload_text

• process_id, host, or title_substring — see Window selection

Typical workflow

1. Call putty_list_windows.
2. Pick a window by process_id (preferred) or title_substring.
3. Optionally call putty_clear_window to remove old scrollback before reading.
4. Call putty_send_command.
5. Wait 1–2 seconds.
6. Call putty_read_window to get the command output.

For AI agents, see AGENTS.md for selection rules, diagnostic markers, and context-reduction tips.

Requirements

• Python 3.10+
• Windows
• pywin32 and mcp[cli] (see Installation)
• One or more PuTTY GUI windows already open (putty.exe)

Installation

git clone https://github.com/pekishev/putty-mcp.git
cd putty-mcp
pip install -r requirements.txt

Or install from pyproject.toml:

pip install .

MCP configuration

Example MCP server entry for Cursor or other MCP clients:

{
  "mcpServers": {
    "putty": {
      "command": "python",
      "args": ["C:/path/to/putty-mcp/putty_mcp.py"]
    }
  }
}

Use the absolute path to putty_mcp.py on your machine.

How it works

• Read — sends PuTTY system command Copy All to Clipboard (IDM_COPYALL) via PostMessage, reads the clipboard, then restores the previous clipboard content.
• Send — resolves the target window and delivers text primarily via clipboard paste (IDM_PASTE). This avoids mid-line truncation of long shell commands that happened with per-character WM_CHAR streams. Control characters (e.g. Ctrl+C) still use WM_CHAR. Messages are posted to the PuTTY hwnd, so a background or maximized window stays where it is: it is not restored, raised, or focused.
• Upload — for payloads beyond the remote tty line limit (~400–500 chars), writes the file with many short printf appends (shell or binary-safe hex encoding) and optionally verifies size with wc -c.
• Clear — sends PuTTY Clear Scrollback (IDM_CLRSB) via system menu command ID; works regardless of UI locale.

PuTTY windows are detected by process name (putty.exe), not by window title alone.

Response format

All tools return JSON objects with a success field.

Examples:

• putty_list_windows → { "success": true, "windows": [{ "title": "...", "pid": 1234 }], "count": 1 }
• putty_read_window → { "success": true, "content": "...", "window_title": "..." }
• putty_send_command → { "success": true, "window_title": "...", "command_sent": "...\n", "activated": false, "delivery": "paste" }
• putty_upload_text → { "success": true, "remote_path": "/tmp/x", "bytes": 2500, "chunks_sent": 21, "encoding": "shell" }
• putty_clear_window → { "success": true, "window_title": "...", "message": "PuTTY scrollback was cleared." }

On errors, responses include error and, when relevant, a windows list to help pick the right target.

Usage notes

• putty_send_command confirms that text was sent; it does not return command stdout. Read output with putty_read_window.
• For content longer than ~400–500 characters, use putty_upload_text instead of one giant putty_send_command (remote tty line limit).
• Prefer process_id over title matching when multiple sessions are open.
• activated reports whether that PuTTY window was already in the foreground. The tool does not change window size, z-order, or focus. A minimized window stays minimized and still receives the command.
• Before diagnostics, use putty_clear_window or marker commands (echo DIAG_START / echo DIAG_END) to reduce noise in long scrollback.

Project layout

putty_mcp.py          # MCP server entry point (FastMCP, stdio transport)
putty_lib/
  window_reader.py    # List/read PuTTY windows
  window_send.py      # Send commands and clear scrollback
  window_upload.py    # Chunked remote file upload via printf

Limitations

• Windows only (pywin32 required).
• Works with existing PuTTY GUI windows; the server does not create SSH sessions.
• Only putty.exe windows are supported (not KiTTY, PuTTYtel, or other forks unless they use the same executable name).
• Reading depends on PuTTY responding to Copy All to Clipboard.

License

MIT