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>();