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.

Covered Executables

Executable	Purpose
putty.exe	GUI terminal sessions (SSH, Telnet, serial, raw)
plink	Command-line SSH/Telnet/serial execution
pscp	SCP/SFTP file transfer
psftp	Interactive SFTP sessions
pageant	SSH key agent
puttygen	Key generation (via ssh-keygen + native PPK converter)

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)

Tool	Description
putty_open	Launch PuTTY with full connection parameters
putty_open_session	Launch PuTTY from a saved session name
putty_serial	Launch PuTTY on a serial port

Command Execution (3)

Tool	Description
plink_exec	Run a single command on a remote host via plink
plink_script	Run commands from a local script file via plink
plink_tunnel	Create SSH tunnel (port forward) or -nc connection

Persistent Sessions (5)

Tool	Description
session_open	Open persistent interactive session (SSH/Telnet/serial/raw)
session_send	Send command to a session and return new output
session_read	Read output buffer from a session
session_list	List all active sessions
session_close	Close a session and clean up

File Transfer (5)

Tool	Description
pscp_upload	Upload file(s) to remote host via pscp
pscp_download	Download file(s) from remote host via pscp
pscp_list	List remote directory via pscp
psftp_batch	Execute SFTP commands as a batch via psftp
psftp_interactive	Open persistent PSFTP session for multi-step workflows

Key Management (6)

Tool	Description
keygen_create	Generate SSH key pair (OpenSSH + PPK format)
keygen_fingerprint	Get fingerprint of an existing key
keygen_convert	Convert key to different format (RFC4716, PKCS8, PEM, PPK)
keygen_public_key	Extract public key in authorized_keys format
pageant_add	Load key(s) into Pageant
pageant_list	List keys loaded in Pageant

Saved Sessions — Registry (4)

Tool	Description
saved_sessions_list	List all PuTTY saved sessions
saved_session_get	Get full config of a saved session
saved_session_create	Create or update a saved session
saved_session_delete	Delete a saved session

Utility (2)

Tool	Description
test_connection	Test SSH/Telnet connectivity, returns host key
get_host_key	Get SSH host key fingerprint from a server

Multi-Hop (2)

Tool	Description
proxy_session	Open interactive session through a proxy command
chain_exec	Execute command on target through one or more jump hosts

Configuration

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

Setting	Default	Description
putty.executable_path	Auto-detected	Path to PuTTY install directory
putty.enable_registry	true	Enable Windows Registry session tools
defaults.protocol	ssh	Default connection protocol
defaults.port	22	Default port
sessions.max_concurrent	10	Max simultaneous interactive sessions
sessions.timeout_seconds	3600	Session idle timeout
sessions.buffer_lines	1000	Output buffer size per session
serial.*	Standard	Default serial parameters (9600/8/N/1)

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