ssh_connect
Establish secure SSH connections to remote servers using password or SSH key authentication for remote operations and management.
Instructions
Connect to an SSH server
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| connectionId | Yes | Unique identifier for this connection | |
| host | Yes | SSH server hostname or IP address | |
| passphrase | No | Passphrase for private key | |
| password | No | SSH password (if not using key) | |
| port | No | SSH port number | |
| privateKeyPath | No | Path to private key file | |
| username | Yes | SSH username |
Implementation Reference
- src/index.ts:539-597 (handler)Implements the core logic for the 'ssh_connect' tool: validates input with ConnectSSHSchema, creates NodeSSH instance, configures connection (host, port, username, password or private key), connects, stores in connectionPool and connectionContexts, returns success message.private async handleSSHConnect(args: unknown) { const params = ConnectSSHSchema.parse(args); if (connectionPool.has(params.connectionId)) { throw new McpError( ErrorCode.InvalidParams, `Connection ID '${params.connectionId}' already exists` ); } const ssh = new NodeSSH(); try { const connectConfig: any = { host: params.host, port: params.port, username: params.username, }; if (params.privateKeyPath) { const privateKey = await fs.readFile(params.privateKeyPath, 'utf8'); connectConfig.privateKey = privateKey; if (params.passphrase) { connectConfig.passphrase = params.passphrase; } } else if (params.password) { connectConfig.password = params.password; } else { throw new McpError( ErrorCode.InvalidParams, 'Either password or privateKeyPath must be provided' ); } await ssh.connect(connectConfig); connectionPool.set(params.connectionId, ssh); // Initialize connection context connectionContexts.set(params.connectionId, { ssh, currentWorkingDirectory: undefined, defaultWorkingDirectory: undefined }); return { content: [ { type: 'text', text: `Successfully connected to ${params.host}:${params.port} as ${params.username} (Connection ID: ${params.connectionId})`, }, ], }; } catch (error) { throw new McpError( ErrorCode.InternalError, `SSH connection failed: ${error instanceof Error ? error.message : String(error)}` ); } }
- src/index.ts:60-67 (schema)Zod schema for validating input parameters to the ssh_connect tool, including host, port, username, optional auth methods, and connectionId.const ConnectSSHSchema = z.object({ host: z.string().describe('SSH server hostname or IP address'), port: z.number().default(22).describe('SSH port number'), username: z.string().describe('SSH username'), password: z.string().optional().describe('SSH password (if not using key)'), privateKeyPath: z.string().optional().describe('Path to private key file'), passphrase: z.string().optional().describe('Passphrase for private key'), connectionId: z.string().describe('Unique identifier for this connection')
- src/index.ts:239-253 (registration)Registers the 'ssh_connect' tool in the ListTools response, providing name, description, and JSON schema mirroring the Zod schema.name: 'ssh_connect', description: 'Connect to an SSH server', inputSchema: { type: 'object', properties: { host: { type: 'string', description: 'SSH server hostname or IP address' }, port: { type: 'number', default: 22, description: 'SSH port number' }, username: { type: 'string', description: 'SSH username' }, password: { type: 'string', description: 'SSH password (if not using key)' }, privateKeyPath: { type: 'string', description: 'Path to private key file' }, passphrase: { type: 'string', description: 'Passphrase for private key' }, connectionId: { type: 'string', description: 'Unique identifier for this connection' } }, required: ['host', 'username', 'connectionId'] },
- src/index.ts:485-486 (registration)Dispatches calls to the 'ssh_connect' tool to the handleSSHConnect handler in the CallToolRequestSchema handler.case 'ssh_connect': return await this.handleSSHConnect(args);
- src/index.ts:22-22 (helper)Global connection pool Map used by ssh_connect to store active NodeSSH connections keyed by connectionId.const connectionPool = new Map<string, NodeSSH>();