ssh-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Common Commands

Installation

pip install ssh-mcp-new

Running the server

ssh-mcp

Config in claude code

tips: you can also add python scripts to your path env, it's all up to you.

  "mcpServers": {
    "ssh-mcp": {
      "command": "C:\\Users\\DELL\\AppData\\Local\\Packages\\PythonSoftwareFoundation.Python.3.11_qbz5n2kfra8p0\\LocalCache\\local-packages\\Python311\\Scripts\\ssh-mcp.exe",
      "args": [],
      "env": {}
    }
  },

Testing with MCP Inspector

npx @modelcontextprotocol/inspector python -m ssh_mcp

Code style

black ssh_mcp/  # Format code
mypy ssh_mcp/   # Type checking

Architecture

This is a single-file MCP server that provides SSH functionality (command execution, file transfer, directory listing) via the FastMCP framework.

Core Patterns

FastMCP Tool Registration: All SSH operations are exposed as MCP tools using @mcp.tool() decorator. Each tool:

• Defines a Pydantic input model for validation
• Returns string-formatted responses (JSON or markdown)
• Uses async functions (though paramiko calls are blocking)

Session Management: SSH connections are stored in a module-level dictionary _ssh_connections keyed by session_id. Sessions persist as long as the server runs.

Input Validation: Each tool has a dedicated Pydantic model (e.g., ConnectInput, ExecuteInput) with:

• Field validators (e.g., _validate_command prevents injection)
• Config with extra='forbid' to reject unknown parameters
• Type annotations for all fields

Response Formatting: Two output formats are supported:

• markdown - human-readable with formatting
• json - machine-readable structured data

Error Handling: _handle_ssh_error() normalizes paramiko exceptions into user-friendly messages covering auth failures, connection issues, timeouts, etc.