JinDaGe - playwright-plus-python-mcp MCP Details

article

README

🚀 Playwright Server MCP

一个基于Playwright的MCP服务器，提供浏览器自动化能力。该服务器可实现笔记存储、提示生成等功能，同时具备丰富的Playwright工具，能满足各种浏览器交互需求。

🚀 快速开始

📦 安装

Claude Desktop配置

MacOS：~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows：%APPDATA%/Claude/claude_desktop_config.json

开发/未发布服务器配置

"mcpServers": {
  "playwright-server": {
    "command": "uv",
    "args": [
      "--directory",
      "C:\\Users\\xxxxx\\Documents\\project\\python\\mcp\\playwright-server",
      "run",
      "playwright-server"
    ]
  }
}

已发布服务器配置

"mcpServers": {
  "playwright-server": {
    "command": "uvx",
    "args": [
      "playwright-server"
    ]
  }
}

✨ 主要特性

🔍 组件

📚 资源

服务器实现了简单的笔记存储系统：

自定义note:// URI方案用于访问单个笔记。
每个笔记资源具有名称、描述和text/plain MIME类型。

💡 提示

服务器提供单个提示功能：

summarize-notes：创建所有存储笔记的摘要。
- 可选style参数控制详细程度（brief/detailed）。
- 生成结合所有当前笔记与样式偏好的提示。

🛠️ 工具

服务器实现以下Playwright相关工具：

会话与导航

playwright_new_session：创建新的浏览器会话并打开浏览器窗口。
- 可选url参数（字符串），指定初始访问网址，不填则只打开浏览器。
playwright_navigate：导航到指定网址。
- 需要url参数（字符串），如不包含http或https前缀将自动添加https://。
- 如果没有活跃的浏览器会话，会自动创建一个新会话。

页面交互与获取内容

playwright_screenshot：对当前页面或特定元素进行截图。
- 需要name参数（字符串），截图文件名称，不需要包含扩展名。
- 可选selector参数（字符串），CSS选择器用于指定要截图的页面元素，不填则截取整个页面。
playwright_evaluate：在浏览器控制台中执行JavaScript代码。
- 需要script参数（字符串），需要在浏览器中执行的JavaScript代码。
playwright_get_text_content：获取当前页面中所有可见元素的文本内容。
- 无需参数。
- 智能过滤重复内容，只返回有意义的文本。
playwright_get_html_content：获取页面中指定元素的HTML内容。
- 需要selector参数（字符串），CSS选择器用于定位需要获取HTML内容的页面元素。

高级交互操作

playwright_action：支持丰富的元素选择与交互方式。
- 必需参数：
  - by：选择元素方式，支持get_by_text、get_by_placeholder、get_by_label、get_by_role等。
  - by_value：选择元素的值。
  - action：操作类型，如fill、click、dblclick、hover、check等。
- 可选参数：
  - value：操作的值。
  - force：是否强制执行动作。
  - delay：按键之间的延迟（毫秒）。
  - 以及更多专用参数，参见代码文档。

🔧 技术细节

⚙️ 配置

系统要求

Python 3.10+
Playwright 1.44+

🚧 开发

构建与发布

准备发布包：

同步依赖并更新锁定文件：

uv sync

构建包分发：

uv build

这将在dist/目录中创建源代码和wheel分发。

发布到PyPI：

uv publish

注意：您需要通过环境变量或命令参数设置PyPI凭据：

令牌：--token或UV_PUBLISH_TOKEN
或用户名/密码：--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器通过stdio运行，调试可能具有挑战性。为获得最佳调试体验，我们强烈推荐使用MCP Inspector。

您可以通过npm使用以下命令启动MCP Inspector：

npx @modelcontextprotocol/inspector uv --directory C:\Users\xxxxx\Documents\project\python\mcp\playwright-server run playwright-server

启动后，Inspector将显示一个URL，您可以在浏览器中访问该URL开始调试。

💻 使用示例

基础用法

# 创建会话并导航到指定网址
await playwright_navigate(url="example.com")

# 截取整个页面
await playwright_screenshot(name="fullpage")

# 截取特定元素
await playwright_screenshot(name="logo", selector=".logo")

高级用法

# 点击文本匹配的按钮
await playwright_action(by="get_by_text", by_value="登录", action="click")

# 填充表单字段
await playwright_action(by="get_by_placeholder", by_value="用户名", action="fill", value="test@example.com")

# 检查元素是否可见
await playwright_action(by="get_by_test_id", by_value="submit-button", action="is_visible")

playwright-plus-python-mcp