Aironin Browse MCP

aiRonin浏览MCP服务器

用于浏览器自动化的模型上下文协议（MCP）服务器，支持Chrome浏览器。

🚀 快速开始

地方发展：

# Install dependencies
npm install

# Start the server
npm start

对于生产/最终用户：

# Use npx (works everywhere)
npx --yes aironin-browse-mcp@1.2.10

对于开发容器：

# Use npx (recommended - handles installation issues automatically)
npx --yes aironin-browse-mcp@1.2.10

# Or install globally with resilient installation
npm install -g aironin-browse-mcp@1.2.10

备注：版本1.2.10+包括增强的开发容器支持：

• ✅ 自动检测受限环境（开发容器、代码空间）
• ✅ 在Puppeter安装过程中优雅地操作SIGTERM
• ✅ 多种回退安装策略
• ✅ 即使本地Chromium安装失败，也能与远程浏览器配合使用
• ✅ 缺少依赖项时的最小服务器模式

📋 MCP配置

标准配置（推荐）

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp@latest"],
      "env": {
        "NODE_ENV": "production",
        "INSTALL_CHROMIUM": "false",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

使用本地Chromium下载

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp@latest"],
      "env": {
        "NODE_ENV": "production",
        "INSTALL_CHROMIUM": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

开发容器配置

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp@latest"],
      "env": {
        "NODE_ENV": "production",
        "INSTALL_CHROMIUM": "false",
        "REMOTE_BROWSER_ENABLED": "true",
        "PUPPETEER_EXECUTABLE_PATH": "/usr/bin/google-chrome"
      }
    }
  }
}

🔧 可用工具

浏览器控件

• launch_browser：启动浏览器并导航到URL
• click_element：在指定坐标处单击
• type_text：在浏览器中键入文本
• scroll_page：向上或向下滚动页面
• hover_element：将鼠标悬停在指定坐标处
• resize_browser：调整浏览器窗口大小
• close_browser：关闭浏览器

截图与分析

• take_screenshot：截图进行AI代理分析
• capture_page：捕获整页屏幕截图
• save_screenshot：截取屏幕截图并保存到磁盘
• analyze_page：分析当前页面内容

HTML源代码检查

• get_page_source：获取当前页面的完整HTML源代码
• get_page_title：获取当前页面的标题
• get_page_meta：提取元标记和其他页面元数据
• inspect_element：获取指定坐标处元素的HTML和属性

🌐 远程浏览器支持

服务器会自动检测并使用：

• 本地Chrome实例
• 远程Chrome实例（包括Docker主机）
• 头戴Chrome以提高可见性

🔧 故障排除

“没有可用的工具”或“找不到服务器信息”

1. 重新启动MCP客户端（光标/继续）
2. 检查Node.js版本是否为20.0.0或更高版本
3. 验证服务器是否正在运行： npx --yes aironin-browse-mcp@1.2.10

开发容器问题

1. 使用最新版本： npx --yes aironin-browse-mcp@1.2.10
2. 服务器将自动使用您的主机Chrome
3. 如果Puppeter安装失败，服务器仍将与远程浏览器一起工作

权限问题

• 使用 npx --yes 避免提示
• 对于全局安装： sudo npm install -g aironin-browse-mcp@1.2.10

木偶安装问题

如果您在开发容器中看到Puppeteer安装错误：

1. 服务器仍将与远程浏览器一起工作
2. 使用以下命令启动Chrome： chrome --remote-debugging-port=9222
3. 服务器将自动检测并连接到远程Chrome

安装问题

1. 找不到包管理器:

   # npm comes bundled with Node.js (default)
   # npm should be available with Node.js installation

   # Or install pnpm (alternative)
   npm install -g pnpm

1. 权限不足:

   # Check permissions
   ls -la ~/.cursor/mcp.json
   chmod 644 ~/.cursor/mcp.json

1. MCP服务器未启动:

   # Test direct execution (choose one)
   npx --yes aironin-browse-mcp  # Using npm (default)
   pnpm dlx aironin-browse-mcp   # Using pnpm (alternative)

浏览器问题

1. Chrome无法启动:

- 确保有足够的磁盘空间 - 检查互联网连接 - 验证Chrome尚未运行

1. 远程浏览器连接失败:

- 使用以下命令启动Chrome： chrome --remote-debugging-port=9222 - 检查防火墙设置

常见错误

1. “找不到命令”:

- 配置更改后重新启动Cursor - 验证您的包管理器是否已安装并位于PATH中 - 对于npm： which npm （应该可以在Node.js中使用） - 对于pnpm： which pnpm

1. “MCP服务器启动失败”:

- 检查Node.js版本（需要20.0.0+） - 验证是否已安装所有依赖项

1. “无可用工具”或“无提示”:

- 添加配置后重新启动MCP客户端（光标、继续等） - 检查日志中MCP服务器是否正确启动 - 验证配置语法是否正确（没有额外的逗号，正确的JSON） - 如果生产不起作用，请尝试开发配置 - 检查Node.js 20.0.0+是否已安装并可用

1. “浏览器自动化失败”:

- 检查Chrome/Chromium安装 - 验证是否有足够的系统资源

📦 安装指南

快速安装

MCP服务器以npm包的形式提供，使用时会自动下载。

选项1:npx（默认）

将此添加到MCP配置中：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

选项2:pnpm-dlx（备选）

将此添加到MCP配置中：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "pnpm",
      "args": ["dlx", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

先决条件

• Node.js：20.0.0或更高
• 程序包管理器:

- npm：9.0.0或更高版本（默认） - pnpm：10.0.0或更高版本（可选）

• 铬/铬：将自动下载
• 光标/继续：MCP兼容AI代理

配置

光标配置

创建或更新 .cursor/mcp.json:

使用npm（默认）：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

使用pnpm（替代）：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "pnpm",
      "args": ["dlx", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

继续配置

创建或更新 ~/.continue/config.json:

使用npm（默认）：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "npx",
      "args": ["--yes", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

使用pnpm（替代）：

{
  "mcpServers": {
    "aironin-browse": {
      "command": "pnpm",
      "args": ["dlx", "aironin-browse-mcp"],
      "env": {
        "NODE_ENV": "production",
        "REMOTE_BROWSER_ENABLED": "true",
        "SCREENSHOT_QUALITY": "75",
        "BROWSER_VIEWPORT_SIZE": "900x600",
        "BROWSER_NAVIGATION_TIMEOUT": "15000"
      }
    }
  }
}

安装选项

默认安装（建议用于开发容器）：

npm install  # Skips Chromium download, uses system/remote Chrome

使用本地Chromium下载：

INSTALL_CHROMIUM=true npm install  # Downloads Chromium locally

便利脚本：

npm run install:no-chromium     # Explicit no-Chromium install
npm run install:with-chromium   # Explicit with-Chromium install
npm run reinstall:no-chromium   # Clean and reinstall without Chromium
npm run reinstall:with-chromium # Clean and reinstall with Chromium

开发设置

git clone 
cd aironin-browse-mcp
npm install  # Uses safe defaults
npm run build
npm start

使用示例

基本浏览器自动化

// Launch browser and navigate
await launch_browser({ url: "https://example.com" });

// Click on an element
await click_element({ coordinates: "200,300" });

// Type text
await type_text({ text: "Hello World" });

// Take screenshot for analysis
await take_screenshot({ quality: 85 });

// Close browser
await close_browser({});

屏幕截图分析

// Take screenshot for AI analysis
await take_screenshot({ quality: 90 });

// Analyze page content
await analyze_page({ includeScreenshot: true });

// Save screenshot to disk
await save_screenshot({ filename: "result", quality: 85 });

HTML源代码检查

// Get full page source
await get_page_source({ includeComments: false });

// Get page title
await get_page_title({});

// Extract meta tags
await get_page_meta({ includeAllMeta: true });

// Inspect element at coordinates
await inspect_element({
  coordinates: "200,300",
  includeChildren: true,
});

验证

要验证您的安装是否正常工作，请执行以下操作：

1. 直接测试MCP服务器:

   # Using npm (default)
   npx --yes aironin-browse-mcp

   # Using pnpm (alternative)
   pnpm dlx aironin-browse-mcp

1. 检查您的MCP客户端日志 对于任何错误消息

1. 重新启动MCP客户端 添加配置后（光标、继续等）

1. 寻找浏览器自动化工具 在您的AI代理的可用工具中

更新

要更新到最新版本：

# For pnpm dlx installation (automatic)
# Just restart your MCP client - it will use the latest version

# For npx installation (automatic)
# Just restart your MCP client - it will use the latest version

# For global npm installation
npm update -g aironin-browse-mcp

然后重新启动MCP客户端（光标、继续等）。

🏗️ 建筑

npm run build

🧪 测试

npm test

📄 许可证

麻省理工学院

🆘 支持

• 问题:
• 文档: README.md
• 讨论: