SSH MCP Server

Instructions

Implementation Reference

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

  The handler function that implements the ssh_connect tool logic. It validates parameters using ConnectSSHSchema, creates a NodeSSH connection, handles authentication with password or private key, adds to connection pool, and 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-68 (schema)

  Zod schema defining the input parameters for the ssh_connect tool, used for validation in the handler.

  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-254 (registration)

  Registration of the ssh_connect tool in the listTools response, including name, description, and JSON input 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 to ssh_connect handler in the CallToolRequestSchema switch statement.

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