SSH MCP Server

Instructions

Implementation Reference

• src/index.ts:893-956 (handler)

  The main handler function for the ssh_start_interactive_shell tool. It parses input using StartInteractiveShellSchema, validates SSH connection and session ID uniqueness, requests an interactive shell via node-ssh with PTY settings, sets up event handlers for data and close events, stores the session in shellSessions map, and returns success message.
  private async handleStartInteractiveShell(args: unknown) { const params = StartInteractiveShellSchema.parse(args); const ssh = connectionPool.get(params.connectionId); if (!ssh) { throw new McpError( ErrorCode.InvalidParams, `Connection ID '${params.connectionId}' not found` ); } if (shellSessions.has(params.sessionId)) { throw new McpError( ErrorCode.InvalidParams, `Session ID '${params.sessionId}' already exists` ); } try { // Create a shell session through SSH const shell = await ssh.requestShell({ cols: params.cols, rows: params.rows, term: 'xterm-256color' }); const emitter = new EventEmitter(); const session: ShellSession = { shell: shell, // SSH ClientChannel ssh, emitter, buffer: '', isActive: true }; // Set up data handling shell.on('data', (data: Buffer) => { const text = data.toString(); session.buffer += text; emitter.emit('data', text); }); shell.on('close', () => { session.isActive = false; emitter.emit('close'); }); shellSessions.set(params.sessionId, session); return { content: [ { type: 'text', text: `Interactive shell session '${params.sessionId}' started successfully\nShell: ${params.shell}\nTerminal: ${params.cols}x${params.rows}`, }, ], }; } catch (error) { throw new McpError( ErrorCode.InternalError, `Failed to start interactive shell: ${error instanceof Error ? error.message : String(error)}` ); } }
• src/index.ts:99-105 (schema)

  Zod schema defining the input parameters for the ssh_start_interactive_shell tool, including connectionId (required), sessionId (required), shell, cols, and rows with defaults and descriptions.
  const StartInteractiveShellSchema = z.object({ connectionId: z.string().describe('SSH connection ID'), sessionId: z.string().describe('Unique identifier for this interactive session'), shell: z.string().default('/bin/bash').describe('Shell to use (e.g., /bin/bash, /bin/zsh)'), cols: z.number().default(80).describe('Terminal columns'), rows: z.number().default(24).describe('Terminal rows') });
• src/index.ts:319-333 (registration)

  Tool registration in the ListTools response, defining name 'ssh_start_interactive_shell', description, and inputSchema matching the Zod schema.
  { name: 'ssh_start_interactive_shell', description: 'Start an interactive shell session with PTY support for typing simulation', inputSchema: { type: 'object', properties: { connectionId: { type: 'string', description: 'SSH connection ID' }, sessionId: { type: 'string', description: 'Unique identifier for this interactive session' }, shell: { type: 'string', default: '/bin/bash', description: 'Shell to use (e.g., /bin/bash, /bin/zsh)' }, cols: { type: 'number', default: 80, description: 'Terminal columns' }, rows: { type: 'number', default: 24, description: 'Terminal rows' } }, required: ['connectionId', 'sessionId'] }, },
• src/index.ts:497-498 (registration)

  Dispatch in the CallToolRequest handler switch statement that routes calls to ssh_start_interactive_shell to the handleStartInteractiveShell method.
  case 'ssh_start_interactive_shell': return await this.handleStartInteractiveShell(args);
• src/index.ts:57-57 (helper)

  Global shellSessions Map that stores active interactive shell sessions, used by the handler.
  const shellSessions = new Map<string, ShellSession>();