# python_playwright_mcp2

**Repository Path**: enzoism/python_playwright_mcp2

## Basic Information

- **Project Name**: python_playwright_mcp2
- **Description**: 使用playwright开发一个MCP的测试Demo
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-08
- **Last Updated**: 2026-05-08

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Playwright MCP Server for Chrome

基于 [Playwright](https://playwright.dev/) 和 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 Chrome/Chromium 浏览器自动化 MCP 服务器。

## 功能特性

本 MCP 服务器为 LLM 提供了完整的浏览器自动化能力，涵盖以下功能模块：

| 模块 | 功能 |
|------|------|
| **浏览器生命周期** | 启动/关闭浏览器、新建/关闭页面 |
| **页面导航** | 打开 URL、刷新、前进、后退 |
| **元素交互** | 点击、双击、填充、输入、按键、悬停、选择、勾选 |
| **鼠标键盘** | 鼠标移动、坐标点击、拖拽、全局键盘输入 |
| **等待机制** | 等待元素、页面加载、网络响应、自定义 JS 条件 |
| **数据提取** | 获取文本、HTML、属性、执行 JS、检查元素状态 |
| **截图录屏** | 页面/元素截图（返回 base64 图片）、PDF 生成 |
| **文件操作** | 文件上传 |
| **弹窗处理** | Alert/Confirm/Prompt 对话框处理 |
| **滚动触摸** | 页面滚动、触摸点击 |

## 安装

```bash
# 使用 uv 安装依赖
uv sync

# 安装 Playwright 浏览器（如果下载超时，可直接使用系统 Chrome，见下方）
playwright install chromium
```

### 使用系统 Chrome（推荐国内用户）

如果 `playwright install` 因网络问题无法下载，可直接使用系统中已安装的 Google Chrome：

```python
# 启动时指定 channel="chrome"
playwright_launch({"headless": true, "channel": "chrome"})
```

支持的 channel：`chrome`、`msedge`、`chromium`。

## 使用方式

### 作为 MCP 服务器运行

```bash
# 直接运行
python -m playwright_mcp_kimi.server

# 或通过入口脚本
playwright-mcp-kimi
```

### 在 MCP 客户端中配置

以 Claude Desktop / Kimi CLI 为例，在配置文件中添加：

```json
{
  "mcpServers": {
    "playwright": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/playwright_mcp_kimi",
        "playwright-mcp-kimi"
      ]
    }
  }
}
```

或使用 Python 直接启动：

```json
{
  "mcpServers": {
    "playwright": {
      "command": "/path/to/playwright_mcp_kimi/.venv/bin/python",
      "args": ["-m", "playwright_mcp_kimi.server"]
    }
  }
}
```

## 工具列表

### 浏览器生命周期
- `playwright_launch` - 启动 Chromium，返回 browser_id / page_id
- `playwright_new_page` - 在浏览器中新建标签页
- `playwright_close_page` - 关闭指定页面
- `playwright_close` - 关闭浏览器及所有页面

### 页面导航
- `playwright_goto` - 导航到 URL（支持 wait_until: load/domcontentloaded/networkidle）
- `playwright_reload` - 刷新页面
- `playwright_go_back` - 后退
- `playwright_go_forward` - 前进

### 元素交互
- `playwright_click` - 点击元素（支持左右键、点击次数）
- `playwright_dblclick` - 双击
- `playwright_fill` - 清空并填充输入框
- `playwright_type` - 逐字输入（可设置延迟）
- `playwright_press` - 在元素上按键（如 Enter）
- `playwright_hover` - 悬停
- `playwright_select_option` - 下拉选择（value/label/index）
- `playwright_check` / `playwright_uncheck` - 勾选/取消勾选

### 鼠标键盘高级
- `playwright_mouse_move` - 鼠标移动到绝对坐标
- `playwright_mouse_click` - 在绝对坐标点击
- `playwright_drag_and_drop` - 拖拽元素到目标
- `playwright_keyboard_type` - 全局键盘输入
- `playwright_keyboard_press` - 全局按键（如 Control+A、F5）

### 等待
- `playwright_wait_for_selector` - 等待元素出现/消失
- `playwright_wait_for_load_state` - 等待页面加载状态
- `playwright_wait_for_timeout` - 固定时间等待
- `playwright_wait_for_response` - 等待网络响应
- `playwright_wait_for_function` - 等待 JS 函数返回 truthy

### 数据提取
- `playwright_get_text_content` - 获取元素文本
- `playwright_get_inner_text` - 获取渲染后文本
- `playwright_get_inner_html` - 获取元素 HTML
- `playwright_get_attribute` - 获取属性值
- `playwright_get_url` - 获取当前 URL
- `playwright_get_title` - 获取页面标题
- `playwright_evaluate` - 执行 JS 并返回结果
- `playwright_is_visible` / `is_hidden` / `is_enabled` / `is_checked`

### 截图与媒体
- `playwright_screenshot` - 截图（返回 base64 图片 + 元数据）
- `playwright_pdf` - 生成 PDF

### 其他
- `playwright_set_viewport` - 设置视口大小
- `playwright_set_input_files` - 上传文件
- `playwright_handle_dialog` - 处理弹窗
- `playwright_scroll` - 滚动页面/元素
- `playwright_tap` - 触摸点击

## 开发

```bash
# 运行测试
pytest tests/ -v

# 代码格式化（推荐）
ruff format src/
ruff check src/
```

## 技术栈

- [Playwright](https://playwright.dev/python/) - 浏览器自动化
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol 服务器
- Python 3.11+

## 协议

MIT