MCP SSH Server

Instructions

Implementation Reference

• src/index.ts:539-597 (handler)

  The handler function for the 'ssh_connect' tool. It validates input parameters using ConnectSSHSchema, creates a new NodeSSH instance, configures connection with host, port, username, and either password or private key, connects to the SSH server, stores the connection in connectionPool and connectionContexts maps, and returns a 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-68 (schema)

  Zod schema used for input validation in the ssh_connect handler, defining parameters like host, port, username, optional password or private key details, and required 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)

  Registration of the 'ssh_connect' tool in the ListTools response, including name, description, and JSON input schema matching 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)

  Dispatch case in the CallToolRequest handler switch statement that routes 'ssh_connect' calls to the handleSSHConnect method.

  case 'ssh_connect':
    return await this.handleSSHConnect(args);