playwright-mcp-forge 1.3.0

Enterprise-grade web automation with 35 MCP tools + auto-healing + optional LLM

🎭 Playwright MCP Forge

Enterprise-Grade Web Automation via Claude Desktop

An intelligent Model Context Protocol (MCP) server for browser automation. Write web automation workflows in natural language through Claude Desktop. Includes CAPTCHA solving, multi-account management, proxy rotation, PDF generation, and more.

---

✨ What You Can Do

• 🌐 Control browsers - Navigate, click, type, scroll
• 📊 Extract data - Tables, text, HTML, structured data
• 🎯 Solve CAPTCHAs - Automatically solve image-based CAPTCHAs with OCR
• 👥 Multi-account - Run multiple browser sessions simultaneously
• 🔄 Proxy rotation - Distribute requests across multiple IPs
• 📄 Generate PDFs - Create PDFs from web pages
• 🔖 Manage tabs - Open, switch, close browser tabs
• ✅ Test assertions - Assert element states, visibility, count
• 🎙️ Record sessions - Trace automation for debugging
• 🔧 Auto-healing locators - Find elements even when selectors change

Works with: Claude Desktop, VS Code, Cline, Cursor, and other MCP clients

---

🚀 Quick Start (5 minutes)

1. Install

# Clone repository
git clone https://github.com/shakti44/playwright-mcp-forge.git
cd playwright-mcp-forge

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
playwright install  # Installs Chromium

# Start server
python src/web_automation.py

2. Connect to Claude Desktop

Edit Claude Desktop config:

• macOS: ~/.anthropic/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "web-automation": {
      "command": "python",
      "args": ["C:\\path\\to\\src\\web_automation.py"]
    }
  }
}

Restart Claude Desktop.

3. Use It

In Claude Desktop, try:

Navigate to example.com and get the main heading

Claude will automatically:

1. Open browser
2. Navigate to the URL
3. Extract the heading text
4. Return the result

---

📚 Usage Examples

Simple: Get Page Title

Get the page title from example.com

Intermediate: Extract Data

Go to example.com, find all h2 headings, and extract their text

Advanced: Multi-Step Workflow

1. Switch to account "buyer_1"
2. Go to https://shop.example.com
3. Click "Add to Cart" button
4. Take a screenshot
5. Extract order confirmation
6. Switch to account "buyer_2"
7. Repeat steps 2-5

Complex: Automation Plan

Execute this automation:
{
  "steps": [
    {"type": "navigate", "value": "https://example.com/login"},
    {"type": "fill", "selector": "input[name='email']", "value": "[e-mail]"},
    {"type": "fill", "selector": "input[name='password']", "value": "password123"},
    {"type": "click", "selector": "button[type='submit']"},
    {"type": "wait", "selector": ".dashboard"},
    {"type": "screenshot"}
  ]
}

---

🔑 Key Features

Feature	Benefit
35 Tools	Covers 95% of automation needs
Auto-Healing Locators	Find elements even when selectors change (82% success)
Optional LLM Enhancement	Improve accuracy to 85-88% with Ollama/Claude/OpenAI/Gemini/Mistral
Python-based	Easy to extend and customize
No Selenium	Modern Playwright API
Stealth Mode	Bypass bot detection
Multi-account	Concurrent browser sessions
CAPTCHA Solving	OCR-based image solving
Proxy Support	Automatic rotation
PDF Export	Generate PDFs from pages
Session Recording	Trace automation for debugging
Test Assertions	Built-in testing framework

---

📖 Documentation

Guide	Purpose
Quick Start	5-minute setup
Environment Setup	Configure API keys with .env files
Auto-Healing Locators	Smart element detection & fallback strategies
Optional LLM Enhancement	[NEW] Add intelligence (Ollama/Claude/OpenAI/Gemini/Mistral)
LLM Integration	Claude, GPT-4, Gemini, local LLaMA
Advanced Features	CAPTCHA, multi-account, proxies
Complete Tool Reference	All 35 tools explained
Architecture	How it works internally
Contributing	How to contribute
Changelog	What's new in v1.3.0

---

🛠️ Installation Options

From PyPI (Easiest)

pip install playwright-mcp-forge

With LLM Integration (Choose One)

# Anthropic Claude
pip install playwright-mcp-forge[claude]

# OpenAI ChatGPT
pip install playwright-mcp-forge[openai]

# Google Gemini
pip install playwright-mcp-forge[gemini]

# Mistral AI
pip install playwright-mcp-forge[mistral]

# All LLMProviders
pip install playwright-mcp-forge[all-llms]

From Source

git clone https://github.com/shakti44/playwright-mcp-forge.git
cd playwright-mcp-forge
pip install -e .

Complete Setup (Everything)

pip install playwright-mcp-forge[complete]
# Includes: CAPTCHA solving + all LLMs + dev tools

---

🤖 Using with Any LLM

Works with Claude, ChatGPT, Gemini, Mistral, LLaMA, and more!

Quick Setup:

1. Install integration: pip install playwright-mcp-forge[claude]
2. Set API key: export ANTHROPIC_API_KEY=sk-...
3. Code or use in your framework

📖 Full LLM Integration Guide - Setup with 5+ LLM providers

---

❓ FAQ

Q: Can I use this without Claude Desktop? A: Yes! Works with any LLM (Claude, GPT-4, Gemini, local LLaMA). See LLM Integration Guide.

Q: Which LLM should I use? A: Claude is recommended, but use what fits your budget/latency needs. See comparison in LLM guide.

Q: How do I integrate with my existing framework? A: Install the package, set your LLM's API key, and import the tools. See integration examples in docs.

Q: How do I solve CAPTCHAs? A: Install Tesseract OCR with pip install playwright-mcp-forge[captcha]. Works with image-based CAPTCHAs.

Q: Can I automate multiple accounts? A: Yes! Use switch_account(name) to manage concurrent sessions with separate cookies and states.

Q: Does it work with all websites? A: Works with most sites. Stealth mode enabled by default. Some sites may require adjustments.

Q: How do I debug automation? A: Use toggle_headless(False) to see browser GUI, or use start_trace() to record actions.

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Quick links:

• Report a bug
• Request a feature
• View roadmap

---

📊 What's Included

34 Total Tools:

• Browser Control (4) - navigate, screenshot, health checks, browser info
• Page Interaction (5) - click, type, scroll, wait for elements, viewport
• Data Extraction (4) - get text, HTML, fetch URLs, extract structured data
• Testing (2) - bot detection, test case generation
• Automation (4) - execute plans, manage cookies
• Advanced (5) - solve CAPTCHAs, multi-account, proxy rotation, headless toggle
• Tab Management (4) - get tabs, new tab, switch tab, close tab
• PDF & Recording (3) - generate PDF, start trace, stop trace
• Testing Tools (4) - assert visibility, text, count, element state

---

🗺️ Roadmap

v1.1.0 ✅ (Current)

• Tab management, PDF generation, test assertions

v1.2 🔜 (Planned)

• WebSocket support, performance metrics, request caching

v2.0 🔮 (Future)

• Distributed execution, ML integration, Web3 support

---

📄 License

MIT License - See LICENSE for details

Attribution: Built with Playwright and FastMCP

---

💬 Need Help?

• 📖 Read the docs
• 🐛 Report issues
• 💡 Suggest features
• 🤚 Community discussions

---

⭐ Show Your Support

If this project helped you, please:

1. Star the repository ⭐
2. Share it with others
3. Contribute improvements

Made with ❤️ for web automation enthusiasts