Imported from reason-machines/mcp-skills (skills/kogiqa-mcp-browser-automation/SKILL.md). Install upstream with npx skills add reason-machines/mcp-skills --skill kogiqa-mcp-browser-automation. Copyright stays with the author.

kogiQA MCP Browser Automation

Skill by ara.so — MCP Skills collection.

Overview

kogiQA MCP is a Model Context Protocol server that provides browser automation capabilities using the kogiQA browser control algorithm. Unlike traditional automation tools, it enables AI agents to interact with web pages through natural language commands without requiring CSS selectors or XPath expressions. This approach saves tokens and simplifies web automation workflows.

Key advantages:

• No selector required — interact with elements using natural language descriptions
• Built on Playwright for robust browser automation
• Works with any MCP-compatible client (Claude Desktop, Cursor, VS Code, etc.)
• Lightweight and easy to install

Installation

Quick Install

The fastest way to install is using npx:

npx kogiqa-mcp@latest

Claude Code

claude mcp add kogiqa-browser npx kogiqa-mcp@latest

VS Code / VS Code Insiders

Install via CLI:

code --add-mcp '{"name":"kogiqa-browser","command":"npx","args":["kogiqa-mcp@latest"]}'

Or add manually to your MCP settings (settings.json):

{
  "mcp.servers": {
    "kogiqa-browser": {
      "command": "npx",
      "args": ["kogiqa-mcp@latest"]
    }
  }
}

Cursor

Add to Cursor Settings → MCP → Add new MCP Server:

{
  "kogiqa-browser": {
    "command": "npx",
    "args": ["kogiqa-mcp@latest"]
  }
}

Standard MCP Configuration

For Claude Desktop, Windsurf, Goose, or other MCP clients, add to your MCP configuration file:

{
  "mcpServers": {
    "kogiqa-browser": {
      "command": "npx",
      "args": ["kogiqa-mcp@latest"]
    }
  }
}

Configuration file locations:

• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: .cursor/config.json in your project or user settings
• VS Code: User or workspace settings

Available Tools

Once installed, the MCP server provides several tools for browser automation:

kogiqa_navigate

Navigate to a URL.

Parameters:

• url (string, required): The URL to navigate to

Example usage:

// AI agent will call this tool as:
kogiqa_navigate({ url: "https://example.com" })

kogiqa_click

Click on an element using natural language description.

Parameters:

• description (string, required): Natural language description of the element to click

Example usage:

// No selectors needed - describe the element naturally
kogiqa_click({ description: "the blue login button" })
kogiqa_click({ description: "submit button at the bottom" })
kogiqa_click({ description: "first link in the navigation menu" })

kogiqa_type

Type text into an input field.

Parameters:

• description (string, required): Natural language description of the input field
• text (string, required): Text to type

Example usage:

kogiqa_type({ 
  description: "email input field", 
  text: "user@example.com" 
})
kogiqa_type({ 
  description: "search box at the top", 
  text: "kogiQA MCP" 
})

kogiqa_get_content

Extract content from the current page.

Returns: HTML or text content of the page

Example usage:

kogiqa_get_content()

kogiqa_screenshot

Take a screenshot of the current page.

Returns: Base64-encoded PNG image

Example usage:

kogiqa_screenshot()

kogiqa_close

Close the browser instance.

Example usage:

kogiqa_close()

Common Patterns

Login Flow Automation

// Navigate to login page
await kogiqa_navigate({ url: "https://app.example.com/login" });

// Fill in credentials
await kogiqa_type({ 
  description: "username field", 
  text: process.env.USERNAME 
});
await kogiqa_type({ 
  description: "password field", 
  text: process.env.PASSWORD 
});

// Submit form
await kogiqa_click({ description: "login button" });

// Verify success
const content = await kogiqa_get_content();

Form Submission

// Navigate to form
await kogiqa_navigate({ url: "https://example.com/contact" });

// Fill multiple fields
await kogiqa_type({ description: "name input", text: "John Doe" });
await kogiqa_type({ description: "email input", text: "john@example.com" });
await kogiqa_type({ description: "message textarea", text: "Hello!" });

// Submit
await kogiqa_click({ description: "send button" });

Web Scraping

// Navigate to target page
await kogiqa_navigate({ url: "https://example.com/products" });

// Extract content
const content = await kogiqa_get_content();

// Take screenshot for verification
const screenshot = await kogiqa_screenshot();

// Parse content (this would be done by the AI agent)
// Extract product names, prices, etc.

Multi-Step Navigation

// Start at homepage
await kogiqa_navigate({ url: "https://example.com" });

// Navigate through site
await kogiqa_click({ description: "products menu item" });
await kogiqa_click({ description: "first product card" });
await kogiqa_click({ description: "add to cart button" });
await kogiqa_click({ description: "checkout button" });

// Capture final state
const screenshot = await kogiqa_screenshot();

Testing with Verification

// Navigate to page under test
await kogiqa_navigate({ url: "https://app.example.com/dashboard" });

// Take before screenshot
const before = await kogiqa_screenshot();

// Perform action
await kogiqa_click({ description: "settings button" });

// Verify change
const content = await kogiqa_get_content();
const after = await kogiqa_screenshot();

// Close when done
await kogiqa_close();

Configuration Options

Headless Mode

By default, kogiQA MCP runs in headless mode. To run with a visible browser (useful for debugging), set environment variables:

{
  "mcpServers": {
    "kogiqa-browser": {
      "command": "npx",
      "args": ["kogiqa-mcp@latest"],
      "env": {
        "HEADLESS": "false"
      }
    }
  }
}

Browser Type

Specify browser (chromium, firefox, webkit):

{
  "mcpServers": {
    "kogiqa-browser": {
      "command": "npx",
      "args": ["kogiqa-mcp@latest"],
      "env": {
        "BROWSER_TYPE": "firefox"
      }
    }
  }
}

Troubleshooting

Server Not Starting

Issue: MCP server fails to start or connect

Solutions:

• Ensure Node.js 20+ is installed: node --version
• Clear npm cache: npm cache clean --force
• Try installing globally: npm install -g kogiqa-mcp@latest
• Check MCP configuration syntax in your client's config file

Browser Launch Failures

Issue: Browser fails to launch or crashes

Solutions:

• Install Playwright browsers: npx playwright install
• Check for system dependencies: npx playwright install-deps
• Try different browser: Set BROWSER_TYPE=firefox or webkit
• Disable headless mode for debugging: HEADLESS=false

Element Not Found

Issue: kogiqa cannot find described element

Solutions:

• Be more specific in element descriptions: "blue submit button at bottom right"
• Include context: "search input in the header"
• Wait for page to load: Get content first to verify page state
• Take screenshot to see current page state

Timeouts

Issue: Operations timeout waiting for elements

Solutions:

• Ensure page has fully loaded before interacting
• Use more specific element descriptions
• Check if element is hidden or covered by other elements
• Verify the element actually exists using kogiqa_get_content

Permission Issues

Issue: Browser automation blocked by website

Solutions:

• Some sites block automation; this is expected behavior
• Check site's terms of service for automation policies
• Consider adding delays between actions
• Use stealth mode if available in future versions

Best Practices

1. Descriptive element references: Be specific but natural ("red delete button in the sidebar" not just "button")
2. Verify page state: Use kogiqa_get_content to confirm page loaded before interacting
3. Handle secrets properly: Use environment variables, never hardcode credentials
4. Close browsers: Call kogiqa_close when done to free resources
5. Progressive navigation: Navigate step-by-step rather than assuming page state
6. Take screenshots: Use for debugging and verification of automation flows
7. Natural language: Write descriptions as you would explain to a human

Resources

• npm package: https://www.npmjs.com/package/kogiqa-mcp
• GitHub repository: atagon-GmbH/kogiqa-mcp
• License: MIT