使用说明

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以提高可见性

🔧 故障排除

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

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

开发容器问题

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

权限问题

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

木偶安装问题

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

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

安装问题

找不到包管理器:

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

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

权限不足:

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

MCP服务器未启动:

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

浏览器问题

Chrome无法启动:
- 确保有足够的磁盘空间
- 检查互联网连接
- 验证Chrome尚未运行
远程浏览器连接失败:
- 使用以下命令启动Chrome： chrome --remote-debugging-port=9222
- 检查防火墙设置

常见错误

“找不到命令”:
- 配置更改后重新启动Cursor
- 验证您的包管理器是否已安装并位于PATH中
- 对于npm： which npm （应该可以在Node.js中使用）
- 对于pnpm： which pnpm
“MCP服务器启动失败”:
- 检查Node.js版本（需要20.0.0+）
- 验证是否已安装所有依赖项
“无可用工具”或“无提示”:
- 添加配置后重新启动MCP客户端（光标、继续等）
- 检查日志中MCP服务器是否正确启动
- 验证配置语法是否正确（没有额外的逗号，正确的JSON）
- 如果生产不起作用，请尝试开发配置
- 检查Node.js 20.0.0+是否已安装并可用
“浏览器自动化失败”:
- 检查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 <repository>
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,
});

验证

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

直接测试MCP服务器:

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

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

检查您的MCP客户端日志 对于任何错误消息
重新启动MCP客户端 添加配置后（光标、继续等）
寻找浏览器自动化工具 在您的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

📄 许可证

麻省理工学院

🆘 支持

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

使用说明

aiRonin浏览MCP服务器

🚀 快速开始

地方发展：

对于生产/最终用户：

对于开发容器：

📋 MCP配置

标准配置（推荐）

使用本地Chromium下载

开发容器配置

🔧 可用工具

浏览器控件

截图与分析

HTML源代码检查

🌐 远程浏览器支持

🔧 故障排除

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

开发容器问题

权限问题

木偶安装问题

安装问题

浏览器问题

常见错误

📦 安装指南

快速安装

选项1:npx（默认）

选项2:pnpm-dlx（备选）

先决条件

配置

光标配置

继续配置

安装选项

开发设置

使用示例

基本浏览器自动化

屏幕截图分析

HTML源代码检查

验证

更新

🏗️ 建筑

🧪 测试

📄 许可证

🆘 支持

相关 MCP

浏览器自动化MCP服务

AKShare One MCP 股市数据服务

实时网络搜索服务

浏览器自动化MCP服务器

网页内容抓取服务

arXiv 论文检索 MCP 服务器