kogiqa-mcp-browser-automation

用途

kogiQA MCP 是一个 Model Context Protocol（MCP）服务器，提供浏览器自动化能力。它使用 kogiQA 浏览器控制算法，让 AI 智能体通过自然语言命令与网页交互，而不需要编写 CSS 选择器或 XPath 表达式。这种方式可以节省 token，并简化网页自动化流程。

主要能力

无需选择器：使用自然语言描述即可与页面元素交互。
基于 Playwright 构建，提供稳健的浏览器自动化。
兼容任意 MCP 客户端，如 Claude Desktop、Cursor、VS Code 等。
轻量且易于安装。

提供的工具

安装后，MCP 服务器提供以下浏览器自动化工具：

kogiqa_navigate：导航到指定 URL。参数 url（字符串，必填）。
kogiqa_click：使用自然语言描述点击元素。参数 description（字符串，必填）。
kogiqa_type：向输入框输入文本。参数 description（字符串，必填）、text（字符串，必填）。
kogiqa_get_content：提取当前页面内容，返回页面的 HTML 或文本内容。
kogiqa_screenshot：对当前页面截图，返回 Base64 编码的 PNG 图像。
kogiqa_close：关闭浏览器实例。

使用方式

安装

最快的方式是使用 npx：

npx kogiqa-mcp@latest

Claude Code：

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

VS Code / VS Code Insiders，通过 CLI 安装：

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

或手动添加到 MCP 设置（settings.json）：

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

Cursor：在 Cursor Settings → MCP → Add new MCP Server 中添加：

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

标准 MCP 配置（适用于 Claude Desktop、Windsurf、Goose 等）：

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

配置文件位置：

Claude Desktop（macOS）：~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop（Windows）：%APPDATA%\Claude\claude_desktop_config.json
Cursor：项目中的 .cursor/config.json 或用户设置
VS Code：用户或工作区设置

配置选项

无头模式：默认以无头模式运行。如需可见浏览器（便于调试），设置环境变量：

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

浏览器类型：可指定 chromium、firefox、webkit：

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

适用场景

登录流程自动化：导航到登录页，填写用户名和密码，提交表单，验证结果。
表单提交：导航到表单页，填写多个字段，点击提交。
网页抓取：导航到目标页，提取内容，截图验证。
多步骤导航：从首页开始，依次点击菜单、产品卡片、加入购物车、结账等。
带验证的测试：导航到被测页面，截图前后对比，验证变化。

限制与注意事项

元素未找到：需更具体地描述元素，包含上下文，等待页面加载，或先获取内容/截图确认页面状态。
超时：确保页面完全加载后再交互，使用更具体的描述，检查元素是否被隐藏或遮挡。
权限问题：部分网站会阻止自动化，这属于预期行为；应检查网站服务条款，考虑在操作间添加延迟。
服务器未启动：确保安装 Node.js 20+，清理 npm 缓存，或尝试全局安装。
浏览器启动失败：安装 Playwright 浏览器（npx playwright install），检查系统依赖，尝试不同浏览器，或禁用无头模式调试。

最佳实践

使用描述性元素引用：具体但自然，例如“侧边栏中的红色删除按钮”而非仅“按钮”。
验证页面状态：交互前用 kogiqa_get_content 确认页面已加载。
妥善处理机密：使用环境变量，切勿硬编码凭据。
关闭浏览器：完成后调用 kogiqa_close 释放资源。
渐进式导航：逐步导航，不要假设页面状态。
截图：用于调试和验证自动化流程。
自然语言：像向人类解释一样编写描述。

资源

npm 包：https://www.npmjs.com/package/kogiqa-mcp
GitHub 仓库：atagon-GmbH/kogiqa-mcp
许可证：MIT