Stagehand × mcp-use基于 Streamlit 与 mcp-use 本地客户端的浏览器自动化聊天界面构建指南【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub导读本文以仓库 stagehand x mcp-use 目录中的 README 为骨架系统讲解如何构建一个100% 本地 MCP 客户端通过mcp-use将 LLM 连接到 MCP 服务器借助 Stagehand MCP 获取浏览器访问与网页自动化能力并用 Streamlit 提供自然语言聊天界面。读完本文你将掌握从依赖安装、环境变量配置、MCP 服务器声明到聊天式驱动浏览器自动化的完整实战流程并理解底层MCPAgent/MCPClient的调用链与可扩展点。项目概览与技术栈该项目是一个 Streamlit 应用其核心定位是用自然语言聊天的方式让 LLM 通过 mcp-use 本地客户端调用 MCP 服务器上的工具完成网页自动化任务。整条技术链路由三部分构成组件作用mcp-use本地 MCP 客户端库负责将 LLM 与任意 MCP 服务器连接提供MCPClient/MCPAgent两个核心类Stagehand MCP提供浏览器访问与网页自动化能力本仓库同时演示了自建的stagehand_mcp.py服务器Ollama本地 LLM 运行时用于浏览器 MCP 服务器的本地模型推理配合OLLAMA_HOST环境变量依赖声明位于 pyproject.tomlmcp-use1.3.10与langchain-openai0.3.30要求 Python 版本3.12。从依赖可以看出LLM 侧通过langchain-openai的ChatOpenAI接入默认使用 OpenAI 兼容接口MCP 侧则完全由mcp-use驱动。环境搭建与配置1. 安装依赖项目使用uv管理 Python 环境一行命令即可完成全部依赖同步uv sync该命令会根据 pyproject.toml 创建虚拟环境并安装mcp-use、langchain-openai等依赖。2. 配置环境变量在项目根目录创建.env文件填入浏览器后端所需的 API 密钥BROWSERBASE_API_KEYyour-browserbase-api-key BROWSERBASE_PROJECT_IDyour-browserbase-project-id其中BROWSERBASE_API_KEY是 Browserbase 云浏览器的访问密钥BROWSERBASE_PROJECT_ID用于标识项目资源。这两个变量会被 MCP 服务器以env形式注入见下文示例配置从而让浏览器会话能够在 Browserbase 云端创建。此外若你的 MCP 服务器需要调用本地 Ollama还应设置OLLAMA_HOST例如http://127.0.0.1:11434README 中的示例配置即采用了这一组合。3. 声明 MCP 服务器仓库提供了一个可直接参考的配置文件 mcp-config.json-example其完整内容如下{ mcpServers: { browserbase: { command: npx, args: [ -y, browserbasehq/mcp-server-browserbase, --modelName, ollama/llama3.2:8b ], env: { BROWSERBASE_API_KEY: your-browserbase-api-key, BROWSERBASE_PROJECT_ID: your-browserbase-project-id, OLLAMA_HOST: http://127.0.0.1:11434 } } } }各字段含义如下command/argsMCP 服务器的启动命令。这里用npx -y browserbasehq/mcp-server-browserbase直接拉取并运行 Browserbase 官方 MCP 服务器--modelName指定浏览器内 AI 模型示例为ollama/llama3.2:8b即让 Stagehand 内部的动作模型走本地 Ollamaenv注入给子进程的环境变量包含上述 Browserbase 凭据与 Ollama 地址。注意配置中的命令路径需根据你的系统环境调整Windows 下可能需改为cmd /c npx等写法。README 明确要求update the paths to the MCP servers according to your system。4. 启动应用streamlit run app.py启动后浏览器会自动打开 Streamlit 界面左侧为 MCP 配置面板右侧为聊天区。界面使用流程应用的使用分为两个阶段对应 app.py 中的核心逻辑阶段一配置并激活 MCP 服务器在侧边栏的 MCP Configuration JSON 文本框中粘贴你的 MCP 服务器配置JSON 格式文本框的placeholder即为内置的示例配置见 app.py这也是 README 中 Load Example Config 所对应的内容{ mcpServers: { stagehand: { command: python, args: [stagehand_mcp.py] } } }即本仓库自带的本地 Stagehand MCP 服务器 3. 点击 Activate Configuration 按钮触发handle_activate()先json.loads解析用户输入再调用_activate()完成 MCP 客户端与 Agent 的初始化。_activate()是整条链路的起点app.pyasync def _activate(cfg_dict: dict): # Create MCPClient from configuration dictionary client MCPClient.from_dict(cfg_dict) # Create LLM llm ChatOpenAI(modelgpt-4o) # Create agent with the client agent MCPAgent(llmllm, clientclient, max_steps30) return client, [], agent其执行的三步值得展开MCPClient.from_dict(cfg_dict)将侧边栏粘贴的 JSON 配置直接转换为 MCP 客户端实例这意味着你无需修改任何代码即可切换任意 MCP 服务器Browserbase 云端、本地 FastMCP 均可ChatOpenAI(modelgpt-4o)通过 langchain-openai 创建驱动 Agent 决策的 LLM。由于接口是 OpenAI 兼容的若你本地有兼容服务如 Ollama 的 OpenAI 端点同样可以替换模型名接入MCPAgent(llmllm, clientclient, max_steps30)将 LLM 与 MCP 客户端绑定为 Agentmax_steps30限制 Agent 单轮任务的推理-行动循环次数上限防止工具调用失控。激活成功后侧边栏会显示 ✅ MCP Client Active 与 ✅ Agent Ready若 JSON 解析失败或初始化异常界面会分别给出 Invalid JSON configuration 或 Failed to activate configuration 的报错提示app.py并自动重置 session 状态。阶段二用自然语言聊天驱动工具配置激活后即可在底部输入框直接与 Agent 对话询问当前 MCP 服务器暴露了哪些工具下达具体的浏览器操作指令如打开某网站并提取标题Agent 会根据任务自主选择合适的 MCP 工具并执行。聊天消息与 Agent 状态均保存在st.session_state中client/agent/tools/activated/config_json/messages因此刷新页面后无需重新激活即可继续会话点击 Clear All 按钮会通过handle_clear()一次性清空全部状态。结合源码深入Agent 与 MCP 服务器的实现细节1. MCPAgent 的关键参数除了 Streamlit 界面仓库还提供了无界面的命令行版示例 server.py它展示了MCPAgent更完整的用法client MCPClient.from_config_file(mcp-config.json) # Create sessions first await client.create_all_sessions() # Discover available tools from MCP server tools set() for name in client.get_server_names(): session client.get_session(name) for t in await session.list_tools(): tools.add(str(getattr(t, name, None) or getattr(t, tool, None) or unknown)) print(Available MCP tools:, sorted(tools)) llm ChatOpenAI(modelgpt-4o-mini) agent MCPAgent( llmllm, clientclient, system_promptYou can browse with Stagehand MCP tools and answer user queries., memory_enabledTrue, max_steps20, ) result await agent.run(Go to example.com and extract the title)这段代码揭示了 mcp-use 的完整调用链也是理解整个项目的钥匙from_config_file()与from_dict()两种等价的客户端构造方式分别从配置文件路径与字典对象读取同一份 MCP 服务器清单create_all_sessions()为每个声明的 MCP 服务器建立会话随后可通过get_server_names()/get_session(name)获取会话并调用list_tools()枚举工具MCPAgent的进阶参数system_prompt定制 Agent 的系统提示词本示例限定其职责为使用 Stagehand MCP 工具浏览网页并回答问题memory_enabledTrue开启会话记忆让多轮对话拥有上下文max_steps20与界面版的30相比更保守适合快速验证agent.run(prompt)单次任务的入口Agent 内部会自主完成规划 → 选工具 → 执行 → 观察结果 → 再规划的循环最后close_all_sessions()关闭全部会话。2. 自建 Stagehand MCP 服务器本仓库并非只能对接 Browserbase 云端服务它还自带了一个本地 MCP 服务器 stagehand_mcp.py基于 FastMCP 实现from mcp.server.fastmcp import FastMCP from stagehand_tool import browser_automation mcp FastMCP(stagehand_mcp) mcp.tool() def browser_automation_tool(task_description: str, website_url: str) - str: Perform browser automation... result browser_automation(task_description, website_url) return result mcp.tool() def add_numbers(a: float, b: float) - dict: Add two numbers together... sum_result a b return {first_number: a, second_number: b, sum: sum_result} if __name__ __main__: mcp.run()从源码结构看该服务器暴露两个工具browser_automation_tool(task_description, website_url)核心工具接收任务描述与目标 URL内部委托给stagehand_tool.py的browser_automation()执行真实浏览器操作失败时捕获RuntimeError并返回结构化错误add_numbers(a, b)一个最简单的工具示例用于验证 MCP 工具发现与调用链路是否通畅可作为链路自检工具。工具的参数均带有类型注解与 docstring这符合 MCP 规范——LLM 正是依靠这些元数据来决定何时调用、传什么参数。3. 浏览器自动化引擎Stagehand LOCAL 模式真正执行浏览器操作的是 stagehand_tool.py它封装了 Stagehand 的完整使用流程config StagehandConfig( envLOCAL, model_namegpt-4o, self_healTrue, system_promptYou are a browser automation assistant that helps users navigate websites effectively., model_client_options{apiKey: os.getenv(MODEL_API_KEY)}, verbose1, ) stagehand Stagehand(config) await stagehand.init() agent stagehand.agent( modelcomputer-use-preview, provideropenai, instructionsYou are a helpful web navigation assistant..., options{apiKey: os.getenv(MODEL_API_KEY)}, ) await stagehand.page.goto(website_url) agent_result await agent.execute( instructiontask_description, max_steps20, auto_screenshotTrue, )要点解析envLOCAL在本地环境运行对应 README 中100% Local的定位无需云端 Stagehand 基础设施self_healTrue开启自愈能力页面元素定位失败时 Stagehand 会自动尝试修复选择器提升自动化鲁棒性model_namegpt-4o与model_client_options{apiKey: ...}浏览器内动作模型及其 API 密钥密钥从环境变量MODEL_API_KEY读取使用前需在.env中补充该变量stagehand.agent(modelcomputer-use-preview, provideropenai, ...)创建基于 OpenAIcomputer-use-preview的计算机使用智能体instructions设定其行为准则不追问、直接完成任务agent.execute(instruction..., max_steps20, auto_screenshotTrue)执行任务描述auto_screenshotTrue让 Agent 在关键步骤自动截图辅助判断外层通过nest_asyncio.apply()允许在已有事件循环内运行异步代码并用asyncio.run()将异步自动化包装成同步函数便于被 FastMCP 工具直接调用。4. 流式工具追踪StreamingMCPAgent 与 ToolCallTracker为了让聊天界面展示Agent 正在做什么仓库提供了 agent_wrapper.py其设计可作为自定义 UI 监控层的最佳实践参考ToolCallTracker内部维护current_tools与tool_history两个列表start_tool_call()记录工具名、参数、状态calling与起始时间complete_tool_call()补充结果超过 200 字符自动截断或错误信息并记录耗时next_step()推进步骤计数并清空当前工具列表StreamingMCPAgent对MCPAgent的包装类通过_patch_agent()拦截agent.runrun_with_streaming()将执行过程拆分为Agent 开始思考 → 分析请求并选择工具 → 逐步执行工具 → 完成几个阶段分别用 Streamlit 的progress_container与可折叠的tool_container.expander( Execution Log)实时呈现执行日志。从源码结构看_monitor_execution()当前以模拟工具列表Navigate → Extract → Process演示进度展示效果真实工具调用结果的接入点已预留——ToolCallTracker的start_tool_call/complete_tool_call接口即为将真实工具执行事件桥接到 UI 的挂载点可自行替换为对MCPAgent内部工具执行的拦截。5. 界面渲染与样式app.py 中_render_hero()以 base64 内嵌图片的方式渲染页头styles.py通过inject_css()注入自定义 CSS包括.main .block-container最大宽度 980px、左对齐聊天气泡与代码块深色背景#1e1e1e的样式定制.bubble-opaque用于任务执行期间显示思考中的占位气泡。端到端工作流总结将以上模块串联起来一次完整的浏览器自动化对话遵循如下链路配置在侧边栏粘贴 MCP 配置 JSON或使用内置的 stagehand 示例点击激活初始化MCPClient.from_dict()解析配置 →ChatOpenAI创建 LLM →MCPAgent绑定两者对话用户输入自然语言指令 → Agent 内部循环枚举可用工具如browser_automation_tool→ 选择匹配工具与参数 → 调用 FastMCP 服务器执行stagehand_tool.py以 LOCAL 模式启动 Stagehandself_heal保证定位稳定性computer-use-preview智能体在页面内逐步执行任务并自动截图回显StreamingMCPAgent将各阶段进度写入界面最终结果以聊天气泡形式展示并持久化到session_state。常见问题与排查建议JSON 配置报错侧边栏会提示 Invalid JSON configuration请检查 JSON 语法与引号是否匹配激活失败提示 Failed to activate configuration优先排查command路径在当前系统是否可用如 Windows 下npx的调用方式、MCP 服务器依赖是否已安装浏览器会话创建失败检查.env中的BROWSERBASE_API_KEY/BROWSERBASE_PROJECT_ID是否正确以及配置 JSON 的env段是否注入了这两个变量本地模型不可用确认 Ollama 服务运行于OLLAMA_HOST指定地址默认http://127.0.0.1:11434且--modelName指定的模型如ollama/llama3.2:8b已拉取调试模式在.env中设置DEBUG_MCP1可开启mcp_use.set_debug(1)输出底层 MCP 通信日志便于定位协议层问题见 app.py。结语Stagehand × mcp-use 展示了现代 AI 浏览器自动化应用的一种轻量落地范式mcp-use 负责 MCP 协议的客户端侧封装Stagehand 负责浏览器内智能体执行Streamlit 负责交互层三者通过标准 MCP 协议解耦。你可以复用这一骨架将配置 JSON 中的服务器换成任意 MCP 服务器或在MCPAgent的system_prompt/memory_enabled/max_steps参数上做文章扩展出属于你自己的本地 Agent 工具台。仓库目录 stagehand x mcp-use 中的 app.py、server.py、stagehand_mcp.py 与 agent_wrapper.py 都是可直接运行、逐段研读的完整示例。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考