# n8n Integration

CloudBrowser MCP Server can be easily integrated with n8n using the HTTP module. This guide will show you step by step how to configure and use the MCP server within your n8n workflows.

## Prerequisites

1. **CloudBrowser API Token**: Get your token from [cloudbrowser.ai](https://cloudbrowser.ai)
2. **n8n Instance**: You need to have n8n running (cloud or self-hosted)
3. **Basic n8n Knowledge**: Familiarity with creating workflows

## Initial Configuration

### Endpoint and Authentication

The CloudBrowser MCP server is available via HTTP at:

* **Endpoint**: `https://mcp.cloudbrowser.ai`
* **Authentication Method**: Bearer Token
* **Authorization Header**: `Bearer your_api_token_here`

## HTTP Module Configuration in n8n

### Step 1: Add an HTTP Request Node

1. In your n8n workflow, add an **HTTP Request** node
2. Configure the following basic parameters:

```json
{
  "method": "POST",
  "url": "https://mcp.cloudbrowser.ai",
  "headers": {
    "Authorization": "Bearer your_api_token_here",
    "Content-Type": "application/json"
  }
}
```

### Step 2: MCP Request Structure

All requests to the MCP server follow this standard structure:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      // Tool-specific arguments
    }
  }
}
```

## Available Tools and Request Examples

### 1. Browser Management

#### Open Browser (`open_browser`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "open_browser",
    "arguments": {
      "keepAlive": 300000,
      "region": "us-east-1",
      "blockAds": true,
      "windowWidth": 1920,
      "windowHeight": 1080,
      "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
    }
  }
}
```

**Expected Response:**

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Browser opened successfully with ID: browser_12345"
      }
    ]
  }
}
```

#### Get Browser List (`get_browsers`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_browsers",
    "arguments": {}
  }
}
```

#### Close Browser (`close_browser`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "close_browser",
    "arguments": {
      "browserId": "browser_12345"
    }
  }
}
```

### 2. Browser Automation

#### Connect to Browser (`connect_to_browser`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "connect_to_browser",
    "arguments": {
      "browserId": "browser_12345"
    }
  }
}
```

#### Navigate to URL (`navigate_to_url`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "navigate_to_url",
    "arguments": {
      "browserId": "browser_12345",
      "url": "https://example.com",
      "waitForLoad": true,
      "timeout": 30000
    }
  }
}
```

#### Get Page Content (`get_page_content`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "get_page_content",
    "arguments": {
      "browserId": "browser_12345",
      "includeHtml": true,
      "includeText": true,
      "includeLinks": true,
      "includeImages": false
    }
  }
}
```

#### Click Element (`click_element`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "click_element",
    "arguments": {
      "browserId": "browser_12345",
      "selector": "button.login-btn",
      "waitForElement": true,
      "timeout": 10000
    }
  }
}
```

#### Type Text (`type_text`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "type_text",
    "arguments": {
      "browserId": "browser_12345",
      "selector": "input[name='username']",
      "text": "my_username",
      "clearFirst": true
    }
  }
}
```

#### Take Screenshot (`take_screenshot`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "take_screenshot",
    "arguments": {
      "browserId": "browser_12345",
      "fullPage": false,
      "quality": 90
    }
  }
}
```

### 3. Session Management

#### Get Saved Sessions (`get_saved_sessions`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_saved_sessions",
    "arguments": {}
  }
}
```

#### Remove Saved Session (`remove_saved_session`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 11,
  "method": "tools/call",
  "params": {
    "name": "remove_saved_session",
    "arguments": {
      "sessionId": "session_12345"
    }
  }
}
```

### 4. Remote Desktop

#### Start Remote Desktop (`start_remote_desktop`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 12,
  "method": "tools/call",
  "params": {
    "name": "start_remote_desktop",
    "arguments": {
      "browserId": "browser_12345"
    }
  }
}
```

#### Stop Remote Desktop (`stop_remote_desktop`)

**Request:**

```json
{
  "jsonrpc": "2.0",
  "id": 13,
  "method": "tools/call",
  "params": {
    "name": "stop_remote_desktop",
    "arguments": {
      "browserId": "browser_12345"
    }
  }
}
```

## Complete n8n Workflow Example

### Use Case: Login Automation and Data Extraction

Here's an example workflow that:

1. Opens a browser
2. Navigates to a website
3. Performs login
4. Extracts data
5. Takes a screenshot
6. Closes the browser

#### Node 1: Open Browser

```json
{
  "method": "POST",
  "url": "https://mcp.cloudbrowser.ai",
  "headers": {
    "Authorization": "Bearer {{ $env.CLOUDBROWSER_TOKEN }}",
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "open_browser",
      "arguments": {
        "keepAlive": 600000,
        "blockAds": true,
        "windowWidth": 1920,
        "windowHeight": 1080
      }
    }
  }
}
```

#### Node 2: Connect and Navigate

```json
{
  "method": "POST",
  "url": "https://mcp.cloudbrowser.ai",
  "headers": {
    "Authorization": "Bearer {{ $env.CLOUDBROWSER_TOKEN }}",
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "navigate_to_url",
      "arguments": {
        "browserId": "{{ $json.result.content[0].text.split('ID: ')[1] }}",
        "url": "https://example.com/login",
        "waitForLoad": true
      }
    }
  }
}
```

#### Node 3: Perform Login

```json
{
  "method": "POST",
  "url": "https://mcp.cloudbrowser.ai",
  "headers": {
    "Authorization": "Bearer {{ $env.CLOUDBROWSER_TOKEN }}",
    "Content-Type": "application/json"
  },
  "body": {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "type_text",
      "arguments": {
        "browserId": "{{ $('Open Browser').first().json.result.content[0].text.split('ID: ')[1] }}",
        "selector": "input[name='username']",
        "text": "my_username"
      }
    }
  }
}
```

## Error Handling

### Common Errors and Solutions

1. **Error 401 - Unauthorized**
   * Verify that your API token is correct
   * Make sure to include the "Bearer " prefix in the header
2. **Error 404 - Browser not found**
   * The browser ID doesn't exist or has expired
   * Verify that you're using the correct browser ID
3. **Error 500 - Internal Server Error**
   * May be a temporary server issue
   * Implement retries with exponential backoff

### Error Handling Example in n8n

```json
{
  "continueOnFail": true,
  "retryOnFail": true,
  "maxRetries": 3,
  "waitBetweenTries": 2000
}
```

## Best Practices

1. **Resource Management**
   * Always close browsers when finished
   * Use appropriate `keepAlive` for your use case
   * Monitor your API quota usage
2. **Performance Optimization**
   * Reuse browsers for multiple operations
   * Use `blockAds: true` for faster pages
   * Implement appropriate timeouts
3. **Security**
   * Never hardcode tokens in workflows
   * Use n8n environment variables for credentials
   * Implement proper logging without exposing sensitive data
4. **Debugging**
   * Use screenshots for visual debugging
   * Implement detailed request/response logging
   * Use n8n test mode for development

## Additional Resources

* [Complete MCP Server Documentation](https://cloudbrowser.gitbook.io/docs/get-started/mcp-server)
* [CloudBrowser API Reference](https://cloudbrowser.gitbook.io/docs/get-started/browser-management)