SSH MCP

Instructions

Implementation Reference

• src/index.ts:302-381 (handler)

  The core handler function that implements the ssh_connect tool logic, establishing SSH connections using password or private key authentication with the ssh2 Client library and managing active connections.
  private async handleSSHConnect(params: any) { const { host, port = 22, username, password, privateKeyPath, passphrase, connectionId = `ssh-${Date.now()}` } = params; // Verify we have either a password or a private key if (!password && !privateKeyPath) { return { content: [{ type: "text", text: "Either password or privateKeyPath must be provided" }], isError: true }; } // Create SSH connection options const sshConfig: any = { host, port, username, readyTimeout: 30000, // 30 seconds timeout for connection }; // Add authentication method if (privateKeyPath) { try { // Expand tilde if present in the path const expandedPath = privateKeyPath.replace(/^~/, os.homedir()); sshConfig.privateKey = fs.readFileSync(expandedPath); if (passphrase) { sshConfig.passphrase = passphrase; } } catch (error: any) { return { content: [{ type: "text", text: `Failed to read private key: ${error.message}` }], isError: true }; } } else if (password) { sshConfig.password = password; } // Create a new SSH client const conn = new Client(); try { // Connect to the server and wait for the "ready" event await new Promise((resolve, reject) => { conn.on("ready", () => { resolve(true); }); conn.on("error", (err: Error) => { reject(new Error(`SSH connection error: ${err.message}`)); }); conn.connect(sshConfig); }); // Store the connection for future use this.connections.set(connectionId, { conn, config: { host, port, username } }); return { content: [{ type: "text", text: `Successfully connected to ${username}@${host}:${port}\nConnection ID: ${connectionId}` }] }; } catch (error: any) { return { content: [{ type: "text", text: `Failed to connect: ${error.message}` }], isError: true }; } }
• src/index.ts:274-291 (registration)

  Registration and dispatch logic in the CallToolRequestSchema handler that routes ssh_connect tool calls to the handleSSHConnect method.
  if (toolName.startsWith('ssh_')) { switch (toolName) { case 'ssh_connect': return this.handleSSHConnect(request.params.arguments); case 'ssh_exec': return this.handleSSHExec(request.params.arguments); case 'ssh_upload_file': return this.handleSSHUpload(request.params.arguments); case 'ssh_download_file': return this.handleSSHDownload(request.params.arguments); case 'ssh_list_files': return this.handleSSHListFiles(request.params.arguments); case 'ssh_disconnect': return this.handleSSHDisconnect(request.params.arguments); default: throw new Error(`Unknown SSH tool: ${toolName}`); } }
• src/index.ts:37-73 (schema)

  Primary input schema definition for the ssh_connect tool declared in the server's capabilities.
  ssh_connect: { description: "Connect to a remote server via SSH", inputSchema: { type: "object", properties: { host: { type: "string", description: "Hostname or IP address of the remote server" }, port: { type: "number", description: "SSH port (default: 22)" }, username: { type: "string", description: "SSH username" }, password: { type: "string", description: "SSH password (if not using key-based authentication)" }, privateKeyPath: { type: "string", description: "Path to private key file (if using key-based authentication)" }, passphrase: { type: "string", description: "Passphrase for private key (if needed)" }, connectionId: { type: "string", description: "Unique identifier for this connection (to reference in future commands)" } }, required: ["host", "username"] } },
• src/index.ts:187-201 (schema)

  Input schema for ssh_connect provided in the ListToolsRequestSchema response.
  name: 'ssh_connect', description: 'Connect to a remote server via SSH', inputSchema: { type: 'object', properties: { host: { type: 'string', description: 'Hostname or IP address of the remote server' }, port: { type: 'number', description: 'SSH port (default: 22)' }, username: { type: 'string', description: 'SSH username' }, password: { type: 'string', description: 'SSH password (if not using key-based authentication)' }, privateKeyPath: { type: 'string', description: 'Path to private key file (if using key-based authentication)' }, passphrase: { type: 'string', description: 'Passphrase for private key (if needed)' }, connectionId: { type: 'string', description: 'Unique identifier for this connection' } }, required: ['host', 'username'] }