PuTTY MCP Server

The full PuTTY toolchain exposed as a Model Context Protocol (MCP) server. Gives AI assistants like Claude complete access to SSH, SCP, SFTP, serial, key management, and more — all through PuTTY's battle-tested Windows tools.

30 tools across 8 categories. Windows-native. Covers every PuTTY executable.

What Makes This Different

Most SSH MCP servers give you basic ssh and scp wrappers. This one wraps the entire PuTTY suite with features you won't find elsewhere:

• Persistent interactive sessions — Open a shell, send commands, read output over multiple turns. Background reader threads keep output flowing.

• Native PPK v3 key conversion — Converts OpenSSH keys to PuTTY's PPK format in pure Python. No GUI puttygen needed.

• Windows Registry integration — Full CRUD for PuTTY saved sessions. Create, read, update, delete sessions programmatically.

• Multi-hop SSH — Chain through jump hosts with automatically constructed proxy commands.

• Serial port support — Open PuTTY on COM ports with configurable baud, parity, stop bits.

• Pageant integration — Load keys into PuTTY's SSH agent.

Related MCP server: R-Shell

Covered Executables

Quick Start

Prerequisites

• Python 3.10+

• PuTTY installed (all tools)

• Windows (PuTTY is Windows-native; registry tools require Windows)

Install

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

Configure Claude Code / Claude Desktop

Add to your MCP config (~/.claude.json or Claude Desktop settings):

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

PuTTY executables are auto-detected from C:\Program Files\PuTTY, PATH, or PUTTY_PATH env var.

Tools (30)

GUI Launch (3)

Command Execution (3)

Persistent Sessions (5)

File Transfer (5)

Key Management (6)

Saved Sessions — Registry (4)

Utility (2)

Multi-Hop (2)

Configuration

Copy config.template.toml to config.toml and adjust as needed:

Architecture

putty_mcp.py              # FastMCP server, all 30 tool definitions
putty_lib/
  config.py               # Path resolution, TOML config loading
  executor.py             # Subprocess wrapper (run, spawn, launch_gui)
  session_manager.py      # Persistent sessions with background readers
  registry.py             # Windows Registry CRUD for saved sessions
  utils.py                # Arg building, host parsing, proxy chains
  ppk.py                  # Native Python PPK v3 writer

Key Design Decisions

• No shell=True — All subprocess calls use argument lists

• ssh-keygen over puttygen — Windows puttygen.exe is GUI-only with no batch CLI. All key generation uses Windows OpenSSH's ssh-keygen, then auto-converts to PPK.

• Native PPK conversion — putty_lib/ppk.py writes PPK v3 format from scratch in Python. Supports Ed25519, RSA, ECDSA. No GUI dependency.

• Thread-safe sessions — Background reader threads with bounded deque buffers and automatic cleanup of timed-out sessions.

Known Limitations

• Pageant key listing: Pageant has no reliable CLI flag to list loaded keys as text. The tool tries ssh-add -L first (requires Pageant started with --openssh-config), falls back to opening the GUI key list window.

• PPK converter: Handles unencrypted keys only. Passphrase-protected keys need manual puttygen GUI conversion.

• Persistent sessions: Return raw ANSI escape codes from remote shells. Functional but noisy.

• Windows only: PuTTY is Windows-native. The registry tools require Windows. Core SSH functionality works anywhere plink is available.

Security

• No shell=True — All commands use subprocess with argument lists

• No credential storage — Keys and passwords are passed per-call, never persisted by the server

• Registry scoped — Only reads/writes PuTTY's own registry keys under HKCU\Software\SimonTatham\PuTTY

License

MIT