1. 为什么要在本地把 Dify 和 Chrome MCP 拼在一起
Dify 本地部署之后，很多人第一反应是接个对话模型做知识库问答，但真正让「AI 助手」从聊天框里走出来、能动手操作网页的，是 MCP（Model Context Protocol）这条线。Chrome MCP 做的事情很直接：它把 Chrome 浏览器包装成一组可被模型调用的工具，截图、点击、填表单、抓数据都能通过标准协议暴露出去。Dify 作为编排层，负责把用户意图翻译成工具调用，再把结果整理成人能看懂的回复。
这套组合适合谁？我总结了三类：一是做内部工具的前端/全栈，想给运营同学一个「说句话就自动跑网页流程」的入口；二是做数据采集的开发者，不想维护一堆 Selenium 脚本，希望用自然语言描述抓取目标；三是研究 Agent 的同学，需要一个本地可控、数据不出内网的浏览器执行环境。它的核心检索词就是「Dify 本地部署 Chrome MCP 网页自动化 AI 助手」，你搜这几个词基本就是这篇要解决的问题。
为什么强调本地？因为浏览器自动化天然涉及登录态、Cookie、内网地址。把 Chrome 跑在自己机器上，MCP 服务监听 127.0.0.1，Dify 也在本地容器里，整条链路不经过外部服务器，敏感页面内容不会外传。代价是配置比纯云端麻烦一点，尤其是 Dify 用 Docker 部署时，容器里的 localhost 和宿主机的 localhost 不是一回事，这个坑后面会专门讲。
还有一个现实问题：模型调用。Dify 本身不提供模型，你得给它配一个 OpenAI 兼容的通道。本地部署场景下，我习惯用 TaoToken 的统一 Key 和 API 通道，一个 Key 走通对话、工具调用、代码生成，省得在 Dify 里维护多套供应商配置。它的 API 地址是 https://taotoken.net/api，兼容 OpenAI 的 /v1/chat/completions 格式，Dify 的模型供应商里选 OpenAI 兼容就能填。
整条链路的角色分工是这样的：Chrome MCP 扩展 + bridge 负责「手」，Dify 负责「大脑编排」，TaoToken 负责「语言能力供给」。三者都跑在本地或本地可访问的网络里，3 分钟跑通的目标是：你在 Dify 里发一句「帮我截取某网页」，Agent 调用 Chrome MCP 的截图工具，返回图片，全程不用写一行胶水代码。
下面按「先备环境 → 起 MCP → 配 Dify → 验证 → 排错」的顺序走，每一步都给可复制的命令和配置。你不需要全部读完再动手，可以边看边敲。
2. 前置准备：Node、Chrome 与 mcp-chrome-bridge 安装踩坑
这一节的目标是让 Chrome MCP 的本地 HTTP 服务在 12306 端口跑起来。先确认基础软件。Node.js 建议 18 以上，我用 nvm 管理版本，避免和系统自带的老 Node 冲突：
# 查看当前版本 node --version npm --version # 如果低于 18，用 nvm 装一个 nvm install 18 nvm use 18Chrome 浏览器必须装，而且要用官方稳定版。macOS 用 Homebrew：
brew install --cask google-chromeUbuntu/Debian 用 apt 仓库方式：
wget -q -O - https://dl.google.com/linux/linux_signing_key.pub | sudo apt-key add - echo "deb [arch=amd64] http://dl.google.com/linux/chrome/deb/ stable main" | sudo tee /etc/apt/sources.list.d/google-chrome.list sudo apt update sudo apt install google-chrome-stable装完用which google-chrome || which chromium-browser确认路径。接下来装桥接工具，它是扩展和本地服务之间的 Native Messaging 中转：
npm install -g mcp-chrome-bridge mcp-chrome-bridge registerregister这一步很关键，它会在系统里注册 Native Messaging host 的清单文件。macOS 下清单一般落在~/Library/Application Support/Google/Chrome/NativeMessagingHosts/，Linux 在~/.config/google-chrome/NativeMessagingHosts/。如果这一步报权限错误，加sudo重跑，但注意 sudo 装出来的全局包路径可能和当前用户不一致，建议先npm config get prefix看清楚。
扩展程序本身要去 GitHub Releases 下载。打开https://github.com/hangwin/mcp-chrome/releases，下载最新版的 zip，解压到一个固定目录，比如~/chrome-mcp-extension。然后在 Chrome 地址栏输入chrome://extensions/，打开右上角「开发者模式」，点「加载已解压的扩展程序」，选中刚才解压的文件夹。加载成功后工具栏会出现扩展图标，点一下，再点「连接」按钮，MCP 服务就会在本地起 HTTP 服务器，默认端口 12306。
验证服务是否活着：
curl http://127.0.0.1:12306/mcp正常会返回一段 MCP 协议相关的 JSON。如果提示Could not connect to server，八成是扩展没点连接，或者 bridge 没注册成功。这时候先回chrome://extensions/看扩展状态，再重跑mcp-chrome-bridge register，然后完全退出 Chrome 再重开——Native Messaging 的注册信息是 Chrome 启动时读取的，不重启不生效。
我踩过的一个坑：公司电脑装了多个 Chrome 渠道（Stable/Beta/Canary），扩展装在 Stable 里，但which google-chrome指向的是另一个，导致 bridge 注册的清单路径和实际运行的浏览器对不上。解决办法是确认你日常用的那个 Chrome 的 user-data-dir，注册时保持一致。另一个坑是端口 12306 被占用，用lsof -i :12306查一下，有输出就杀掉或改扩展端口。
到这里，「手」就准备好了。下一节把它接到 Dify 上。
3. 可复制配置：Dify 接入 Chrome MCP 的 JSON 与模型通道
Dify 本地部署通常用 Docker Compose，容器网络是独立的一套。这里最容易翻车：你在宿主机上curl 127.0.0.1:12306通，但 Dify 容器里访问127.0.0.1是容器自己，不是宿主机。所以 MCP 的 URL 必须写成宿主机在容器网络里的可达地址。
macOS 和 Windows 的 Docker Desktop 提供了host.docker.internal这个特殊域名，直接用它：
{ "name": "Chrome MCP", "description": "Chrome 浏览器自动化工具，支持网页截图、表单填写、数据抓取", "connection": { "type": "http", "url": "http://host.docker.internal:12306/mcp" }, "timeout": 30000 }Linux 上host.docker.internal默认不解析，有两个办法：一是启动 Dify 的 compose 时给服务加extra_hosts: ["host.docker.internal:host-gateway"]；二是直接填宿主机在 docker0 网桥上的 IP，通常是172.17.0.1，用ip addr show docker0确认。填172.17.0.1:12306也能通，但宿主机 IP 变了要改，不如 host-gateway 稳。
在 Dify 控制台的操作路径：进入「工具」→「添加工具」→ 选「MCP 工具」类型 → 把上面的 JSON 粘进配置框 → 点「测试连接」。显示连接成功后保存并启用。注意 Dify 版本不同，MCP 工具的入口位置略有差异，较新版本在「工具」页直接有 MCP 分类，老版本可能要在「插件」里找。
接下来配模型通道。Dify 的「设置」→「模型供应商」里选 OpenAI 兼容类型，填三件套：
| 配置项 | 值 |
|---|---|
| Base URL | https://taotoken.net/api |
| API Key | 在 TaoToken 控制台创建的 Key |
| Model ID | 按你需要的模型填，如 claude-sonnet 系列或 gpt 系列 |
Base URL 这里有个细节：Dify 的 OpenAI 兼容供应商有的版本要求填到/v1，有的填根路径自动补。如果测试时报 404，把 Base URL 改成https://taotoken.net/api/v1再试。Key 的创建入口在控制台的 API Keys 页面，建议给 Dify 单独建一个 Key，方便按项目统计用量和随时吊销。
模型选型上，网页自动化任务对「工具调用」能力要求高，选支持 function calling 的模型。纯对话模型虽然能聊，但不会主动调 MCP 工具，Agent 就退化成聊天机器人了。在 Dify 的 Agent 应用里，把 Chrome MCP 工具勾选上，模型选刚才配的通道，系统提示词里明确告诉它「需要操作网页时调用 Chrome MCP 工具」。
如果你用的是 Claude Code 这类编码场景，TaoToken 的 Coding Plan 也能覆盖，但本篇聚焦 Dify，模型通道配好就够。配置片段建议存成文件备份，Dify 升级或迁移时直接复用，省得重填。
4. 验证请求：从 tools/list 到端到端截图任务
配置完先别急着建应用，用 curl 直接打 MCP 服务，确认工具列表能拉出来：
curl -X POST http://127.0.0.1:12306/mcp \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'返回里应该能看到tools数组，包含截图、点击、填表、导航等工具名和参数 schema。这一步通了，说明 Chrome MCP 本身没问题。如果返回空数组或报错，回上一节检查扩展连接状态。
然后在 Dify 里建一个 Agent 应用，系统提示词可以这样写：
你是一个网页自动化助手。当用户要求截图、抓取或填写网页时，调用 Chrome MCP 工具完成。调用前先确认目标 URL 有效，操作完成后用简洁中文汇报结果。
测试对话输入：「帮我截取 https://example.com 的整页截图」。正常情况下，Dify 会触发工具调用，Chrome MCP 在浏览器里打开页面、截图、把图片作为工具结果返回，Agent 再把图片展示在对话里。第一次跑可能会慢几秒，因为要等页面加载。
如果 Agent 不调工具，只回文字，检查三件事：模型是否支持 function calling、工具是否在应用里启用、提示词是否明确要求调用工具。我遇到过模型「礼貌地拒绝」调工具的情况，把提示词改成「必须调用工具，不要凭记忆回答」就正常了。
再验证一个抓取任务：「打开某商品页，提取标题和价格」。Chrome MCP 会返回页面文本或结构化数据，Agent 整理后输出。这一步能跑通，说明端到端链路完整：Dify 编排 → TaoToken 模型通道 → Chrome MCP 执行 → 结果回传。
验证阶段建议开两个终端，一个tailDify 的容器日志，一个看 Chrome MCP 的返回，出问题时能快速定位是模型没调工具、还是工具执行失败、还是结果没回传。日志里搜tool_call和mcp关键字，基本能还原调用链。
5. 常见报错排查：401、local proxy failed 与 reading choices
排错这节按真实报错来，都是我在本地部署时撞过的。
401 Unauthorized：出现在 Dify 调模型时。原因通常是 API Key 填错、Key 被吊销、或者 Base URL 和 Key 不匹配（比如把 A 平台的 Key 填到 B 平台的地址）。解决：去 TaoToken 控制台确认 Key 有效，重新复制粘贴，注意别带空格。如果 Dify 日志里显示invalid_api_key，就是这个。
local proxy failed / connection refused：Dify 容器访问 MCP 地址失败。九成是127.0.0.1没换成host.docker.internal或宿主机 IP。用docker exec -it <dify容器名> curl http://host.docker.internal:12306/mcp在容器内测一下，不通就是网络问题。Linux 记得加extra_hosts。
reading choices 报错：模型返回体解析失败，常见于 Base URL 少写或多写/v1，导致请求打到了错误端点，返回的不是标准 OpenAI 格式。把 Base URL 在https://taotoken.net/api和https://taotoken.net/api/v1之间切换试一次，看哪个返回正常。
OAuth / 扩展未连接：Chrome MCP 扩展显示「未连接」。重跑mcp-chrome-bridge register，重启 Chrome，再点扩展的连接按钮。如果还不行，检查 Native Messaging 清单文件里的扩展 ID 是否和chrome://extensions/里显示的一致，不一致说明注册时用的路径不对。
工具调用超时：timeout设的 30000 毫秒对复杂页面可能不够，改成 60000。同时确认 Chrome 没被其他自动化脚本占用，同一时间一个标签页只服务一个任务比较稳。
模型不调工具：不是报错但很常见。换支持 function calling 的模型，或在 Dify 里把工具调用模式设为「强制」。提示词里加一句「所有网页操作必须通过工具完成」。
排查顺序建议：先 curl 直连 MCP 确认服务活着 → 再容器内 curl 确认网络通 → 再看 Dify 日志确认模型请求发出 → 最后看模型返回是否含 tool_calls。按这个链路走，基本不会卡住。
6. 把链路固定下来：Key 管理、模型切换与长期维护
跑通之后，日常维护主要盯三件事：Key、模型、扩展版本。
Key 管理上，给 Dify 单独建 Key，别和编码工具共用。TaoToken 控制台可以按 Key 看用量，Dify 的调用量突增时能快速定位是哪个应用在跑。如果 Key 泄露，直接吊销重建，Dify 里改一处配置即可，不影响 Chrome MCP。
模型切换很灵活，因为走的是统一通道，换 Model ID 就行，不用改 Base URL 和 Key。做网页自动化时，复杂页面解析用能力强的模型，简单截图任务用轻量模型省成本。在 Dify 里可以配多个模型供应商实例，按应用选。
扩展版本要跟。Chrome MCP 更新较快，新版本可能修了页面兼容问题。升级时重新下载 Releases 里的 zip，在chrome://extensions/里点「重新加载」，bridge 一般不用重装，除非 release notes 明确要求。
长期跑的话，建议把 Chrome 单独开一个用户目录，别和你日常浏览的混在一起：
open -a "Google Chrome" --args --user-data-dir=/tmp/chrome-mcp-profile这样自动化用的登录态、Cookie 和日常隔离，互不干扰。任务多的时候，一个 Chrome 实例专注一个流程，避免标签页互相抢焦点。
最后，Dify 的 Agent 应用可以发布成 Web App 或 API，给内部同学用。发布前把系统提示词打磨好，明确工具使用边界，比如「不要自动提交表单，提交前必须让用户确认」。网页自动化涉及真实操作，加一道确认能避免误点。
整条链路的核心价值是：本地可控、数据不出内网、模型通道统一。你把这套配好，后面加新的 MCP 工具（比如文件系统、数据库）也是同样的接法，Dify 里加工具、模型通道不变，扩展性很好。
