SSH MCP

Instructions

Implementation Reference

• src/index.ts:302-381 (handler)

  Implements the ssh_connect tool by creating an SSH connection using the ssh2 Client, supporting password or private key authentication, storing the connection in a map for later use, and returning appropriate success or error responses.

  private async handleSSHConnect(params: any) {
    const {
      host,
      port = 22,
      username,
      password,
      privateKeyPath,
      passphrase,
      connectionId = `ssh-${Date.now()}`
    } = params;
  
    // Verify we have either a password or a private key
    if (!password && !privateKeyPath) {
      return {
        content: [{ type: "text", text: "Either password or privateKeyPath must be provided" }],
        isError: true
      };
    }
  
    // Create SSH connection options
    const sshConfig: any = {
      host,
      port,
      username,
      readyTimeout: 30000, // 30 seconds timeout for connection
    };
  
    // Add authentication method
    if (privateKeyPath) {
      try {
        // Expand tilde if present in the path
        const expandedPath = privateKeyPath.replace(/^~/, os.homedir());
        sshConfig.privateKey = fs.readFileSync(expandedPath);
        
        if (passphrase) {
          sshConfig.passphrase = passphrase;
        }
      } catch (error: any) {
        return {
          content: [{ type: "text", text: `Failed to read private key: ${error.message}` }],
          isError: true
        };
      }
    } else if (password) {
      sshConfig.password = password;
    }
  
    // Create a new SSH client
    const conn = new Client();
    
    try {
      // Connect to the server and wait for the "ready" event
      await new Promise((resolve, reject) => {
        conn.on("ready", () => {
          resolve(true);
        });
        
        conn.on("error", (err: Error) => {
          reject(new Error(`SSH connection error: ${err.message}`));
        });
        
        conn.connect(sshConfig);
      });
      
      // Store the connection for future use
      this.connections.set(connectionId, { conn, config: { host, port, username } });
      
      return {
        content: [{ 
          type: "text", 
          text: `Successfully connected to ${username}@${host}:${port}\nConnection ID: ${connectionId}` 
        }]
      };
    } catch (error: any) {
      return {
        content: [{ type: "text", text: `Failed to connect: ${error.message}` }],
        isError: true
      };
    }
  }

• src/index.ts:37-73 (schema)

  Primary input schema definition for the ssh_connect tool, declared in server capabilities.

  ssh_connect: {
    description: "Connect to a remote server via SSH",
    inputSchema: {
      type: "object",
      properties: {
        host: {
          type: "string",
          description: "Hostname or IP address of the remote server"
        },
        port: {
          type: "number",
          description: "SSH port (default: 22)"
        },
        username: {
          type: "string",
          description: "SSH username"
        },
        password: {
          type: "string",
          description: "SSH password (if not using key-based authentication)"
        },
        privateKeyPath: {
          type: "string",
          description: "Path to private key file (if using key-based authentication)"
        },
        passphrase: {
          type: "string",
          description: "Passphrase for private key (if needed)"
        },
        connectionId: {
          type: "string",
          description: "Unique identifier for this connection (to reference in future commands)"
        }
      },
      required: ["host", "username"]
    }
  },

• src/index.ts:276-277 (registration)

  Dispatches ssh_connect tool calls to the handleSSHConnect handler in the CallToolRequestSchema switch statement.

  case 'ssh_connect':
    return this.handleSSHConnect(request.params.arguments);

• src/index.ts:186-202 (schema)

  Duplicate input schema for ssh_connect returned by the ListToolsRequestSchema handler.

  {
    name: 'ssh_connect',
    description: 'Connect to a remote server via SSH',
    inputSchema: {
      type: 'object',
      properties: {
        host: { type: 'string', description: 'Hostname or IP address of the remote server' },
        port: { type: 'number', description: 'SSH port (default: 22)' },
        username: { type: 'string', description: 'SSH username' },
        password: { type: 'string', description: 'SSH password (if not using key-based authentication)' },
        privateKeyPath: { type: 'string', description: 'Path to private key file (if using key-based authentication)' },
        passphrase: { type: 'string', description: 'Passphrase for private key (if needed)' },
        connectionId: { type: 'string', description: 'Unique identifier for this connection' }
      },
      required: ['host', 'username']
    }
  },