Navagent MCP

导航代理

](https://www.npmjs.com/package/navagent-mcp) 

超轻MCP浏览器导航。令牌高效和反机器人。适用于任何网站（SPA、影子DOM、iframe）。

AI看到的是一个紧凑的编号列表，而不是屏幕截图或冗长的可访问性树：

AI sees:                   AI does:
────────────               ─────────────
📍 amazon.com              browse_click(6)
1. My Account [link]
2. Cart (0) [link]
3. Search [input]
4. Computers [link]
5. Electronics [link]
6. Books [link]

为什么选择NavAgent？

• 代币高效 --编号列表而不是屏幕截图（约2000+个标记）或ARIA树（约15-20k个标记）
• 防机器人 --使用Chrome的原生扩展消息传递，而不是CDP。Cloudflare、Akamai等无法检测到。
• 随时随地工作 --SPA（哈希路由）、shadow DOM（强制打开）、同源iframe、内容可编辑编辑器（DraftJS、ProseMirror）
• 通用MCP --适用于Claude Code、Claude Desktop、Cursor、Windsurf、Zed和任何MCP客户端
• 真实浏览器会话 --您的Cookie、登录信息、无云代理
• 零遥测 --无跟踪，完全开源

建筑

MCP Client (Claude Code, Cursor, Claude Desktop, etc.)
    ↓ stdio (Model Context Protocol)
navagent-mcp (npm package)
    ↓ WebSocket localhost:61822
Chrome Extension
    ↓ chrome.tabs.sendMessage
Content Script (DOM scanner)

需要两个组件：

快速开始

1.安装Chrome扩展程序

Chrome网络商店 （推荐）： 安装NavAgent

或侧面加载：

1. 克隆此仓库
2. 打开 chrome://extensions/
3. 启用 开发者模式
4. 点击 加载未打包的 → 选择 chrome-extension/ 文件夹

2.将MCP服务器添加到您的AI客户端

Claude Code

添加 .mcp.json （项目或全球 ~/.claude.json):

{
  "mcpServers": {
    "navagent": {
      "command": "npx",
      "args": ["-y", "navagent-mcp"]
    }
  }
}

Claude Desktop

编辑 claude_desktop_config.json:

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "navagent": {
      "command": "npx",
      "args": ["-y", "navagent-mcp"]
    }
  }
}

Cursor

编辑 ~/.cursor/mcp.json:

{
  "mcpServers": {
    "navagent": {
      "command": "npx",
      "args": ["-y", "navagent-mcp"]
    }
  }
}

Windsurf

编辑 ~/.windsurf/mcp.json:

{
  "mcpServers": {
    "navagent": {
      "command": "npx",
      "args": ["-y", "navagent-mcp"]
    }
  }
}

Zed

编辑 settings.json → context_servers:

{
  "context_servers": {
    "navagent": {
      "command": {
        "path": "npx",
        "args": ["-y", "navagent-mcp"]
      }
    }
  }
}

OpenClaw

添加 openclaw.json → mcp.servers:

{
  "mcp": {
    "servers": {
      "navagent": {
        "command": "npx",
        "args": ["-y", "navagent-mcp"],
        "transport": "stdio"
      }
    }
  }
}

Any MCP-compatible client

NavAgent使用stdio传输。配置您的客户端以运行：

command: npx
args: ["-y", "navagent-mcp"]

3.验证

1. Chrome浏览器已打开，NavAgent扩展程序已启用
2. 启动您的MCP客户端
3. 问AI： *首选https://example.com并扫描页面”*

可用工具（12）

运作原理

元素检测：

• 可点击性强： `, , , , , [contenteditable]ARIA交互角色、内联处理程序， tabindex >= 0`
• 可点击性较弱： cursor: pointer, data-* 属性、框架指令(@click, v-on:click, ng-click)
• SPA哈希路由(#/path/..., #!/hashbang)检测为导航链接

高级功能：

• 影子DOM — shadow-hook.js 力量 attachShadow({mode:'open'}) 在页面脚本之前。Walker遍历所有影子根，包括看不见的宿主。
• 同源iframe --walker通过以下方式跨越iframe边界 contentDocument （OVH Manager等微前端架构）
• 内容可编辑 — execCommand('insertText') 丰富的编辑（DraftJS、ProseMirror）。快速、框架兼容、不可检测。
• 区域检测 --地标性建筑(nav, header, footer, aside, dialog, [aria-modal])用于复杂页面上的结构化导航
• 安全扫描 --徒步旅行 querySelectorAll 回退捕捉树行者错过的元素

经过测试

配置

自定义WebSocket端口

违约： 61822。要更改：

1. 集 NAVAGENT_PORT 在MCP配置中：

{
  "mcpServers": {
    "navagent": {
      "command": "npx",
      "args": ["-y", "navagent-mcp"],
      "env": { "NAVAGENT_PORT": "61900" }
    }
  }
}

1. 在Chrome扩展程序选项页面中设置相同的端口。

安全

• WebSocket正在监听 仅限本地主机 (127.0.0.1)--无外部连接
• 扩展使用最小权限： activeTab, storage, alarms
• 没有遥测，没有数据发送到任何地方
• 用途 chrome.tabs.sendMessage （本机扩展消息传递），不是CDP--否 navigator.webdriver 反机器人系统无法检测到的标志

发展

cd mcp-server
npm install
npm test        # 111 tests (vitest + jsdom)

作者

迪米特里·布里兹-- dimitri.bouriez.dev@gmail.com

许可证

麻省理工学院