tonyhzk/chrome-agent-skill

---

Features

Core Capabilities

• Page Navigation - Navigate to URLs, go back/forward
• Element Interaction - Click (ref or coordinates), hover, type text, select options, drag elements
• Element Search - Search elements by keyword, get element coordinates
• Multi-Tab Management - List, open, switch, close tabs
• Screenshots - Capture visible page as PNG (save to file or return base64)
• Page Snapshots - Get ARIA accessibility tree for structured page analysis
• Page Content - Get plain text content, full HTML source code
• Keyboard Input - Press any key, submit forms
• Console Logs - Retrieve browser console output

Architecture

The server communicates with the Browser MCP Chrome extension over WebSocket. Commands are sent as JSON via stdin, and results are returned via stdout.

Additional Tools

• Batch URL Resolver - Resolve redirect URLs in bulk via HTTP requests (no browser required)

---

System Requirements

---

Installation

1. Clone the Repository

git clone https://github.com/Tonyhzk/chrome-agent-skill.git

2. Install the Chrome Extension

1. Open chrome://extensions/ in Chrome
2. Enable Developer mode
3. Unzip the .zip extension package from src/browser-chrome-agent/assets/, then click “Load unpacked” and select the unzipped directory; or load the src/browser-mcp-crx/ source directory directly
4. Pin the Browser MCP extension for easy access

3. Install Python Dependencies

pip3 install websockets

4. Set Up Shared Configuration (Optional)

If you use a shared .claude configuration across projects:

python3 setup_claude_dir.py

This creates a symlink from the project’s .claude directory to your shared configuration.

---

Quick Start

1. Start the WebSocket Server

python3 src/browser-chrome-agent/scripts/server.py --port 9009

2. Connect the Extension

Click the Browser MCP extension icon in Chrome and click Connect.

3. Send Commands

Send JSON commands via stdin (one per line):

{"action": "navigate", "params": {"url": "https://example.com"}}
{"action": "snapshot", "params": {}}
{"action": "click", "params": {"ref": "s1e5"}}
{"action": "screenshot", "params": {"savePath": "./screenshot.png"}}

---

Available Actions

Element References

Interactive actions (click, hover, type, etc.) use ref values from the ARIA snapshot to target elements. Use find_element or find_and_locate to search elements by keyword and get their refs or coordinates directly. Use snapshot only when you need to inspect the full page structure.

---

Project Structure

chrome-agent-skill/
├── src/browser-chrome-agent/
│   ├── SKILL.md              # Skill definition
│   ├── scripts/
│   │   ├── server.py         # WebSocket server (main entry)
│   │   ├── context.py        # WebSocket connection manager
│   │   ├── tools.py          # Browser automation tools
│   │   ├── utils.py          # Utility functions
│   │   ├── batch_resolve_urls.py  # Batch URL resolver
│   │   └── requirements.txt  # Python dependencies
│   └── assets/               # Chrome extension packages
├── src/browser-mcp-crx/      # Modified Chrome extension source code
├── upstream/                 # Original Browser MCP extension & source archive
├── 0_Doc/                    # Documentation
├── 0_Design/                 # Design resources
├── setup_claude_dir.py       # Shared config symlink tool
├── CHANGELOG.md              # English changelog
└── CHANGELOG_CN.md           # Chinese changelog

---

Acknowledgements

This project is a Python rewrite of Browser MCP (originally TypeScript/Node.js), adapted as a Claude Code Skill with a WebSocket-based stdin/stdout control interface.

• Browser MCP - The original project and Chrome extension that powers browser automation

License

Apache License 2.0

Author

Tonyhzk

• GitHub: @Tonyhzk
• Email: [email protected]