mcpwright
Browser automation that AI agents actually understand.
The problem (why this exists)
You give your AI agent a task: "Log in to LinkedIn and send 5 recruiters a personalized message."
The agent tries. It clicks. It types. It crashes.
Why?
- The website uses React — the agent types into a
<div>, but React's state never updates, so the Send button stays disabled. - The page lazy-loads — the agent clicks before the button exists.
- The site uses CAPTCHA / bot detection — fast clicks get the account flagged.
- The agent doesn't know the page is still loading — it tries to click a "Submit" button that doesn't exist yet.
- The login session expires — the agent reuses a stale cookie and gets bounced.
There is no clean, open-source solution today that solves all of this for AI agents specifically. Most automation libraries (Selenium, Playwright raw, Puppeteer) were built for test automation — humans writing scripts, not LLMs driving them.
mcpwright is built for AI agents first. Every default is tuned for the way an LLM thinks, types, and clicks.
What mcpwright does
mcpwright is a Python library that sits on top of Playwright's Model Context Protocol (MCP) server and adds the missing layer that AI agents need:
| What goes wrong without mcpwright | What mcpwright does |
|---|---|
| React apps don't respond to fake typing | Uses real keyboard input through the MCP bridge, so React state updates |
| Agent clicks before page is ready | Waits for actual page state, not fixed sleeps |
| Site rejects fast clicking | Smart pacing — learns the site's tolerance |
| Login cookies expire | Reuses your saved browser profile (LinkedIn stays logged in) |
| One selector breaks | Selector fallback — tries 3+ ways to find the same element |
| First attempt fails | Auto-retry with exponential backoff |
| Agent doesn't know if a click worked | Visual + DOM verification after every action |
npm not in PATH on Windows |
Cross-platform npx path resolution baked in |
| Different OS = different paths | Same Python code runs on Windows / WSL2 / Linux / macOS |
30-second quick start
1. Install
pip install mcpwright
That's it. Once published to PyPI, this will be pip install mcpwright — for now, clone this repo and pip install -e . to get started.
2. Make sure Playwright MCP is available
npx -y @playwright/mcp@latest --help
If npx isn't found, install Node.js from nodejs.org.
3. Your first script
# examples/01_basic_navigate.py
from mcpwright import browser_session
with browser_session(profile_path="<PATH_TO_YOUR_CHROME_PROFILE>") as (send, recv):
# Navigate
send({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "browser_navigate",
"arguments": {"url": "https://example.com"}}})
response = recv()
# Take a screenshot
send({"jsonrpc": "2.0", "id": 2, "method": "tools/call",
"params": {"name": "browser_take_screenshot",
"arguments": {"fullPage": True}}})
response = recv()
Run it: python examples/01_basic_navigate.py
That's the entire surface. You now have an LLM-controllable browser.
A real example: apply to 5 jobs
# examples/03_naukri_apply.py
from mcpwright import browser_session, smart_wait, react_aware_type
with browser_session(profile_path="<YOUR_CHROME_PROFILE>") as (send, recv):
# 1. Search
send({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "browser_navigate",
"arguments": {"url": "https://example.com/jobs?q=power+bi"}}})
recv()
# 2. Wait for jobs to load (NOT a fixed sleep)
smart_wait(send, recv, condition="list_selector_present",
selector="[data-job-id]", timeout=20)
# 3. Click first 5 jobs and apply
for i in range(1, 6):
# ... full implementation in examples/03_naukri_apply.py
pass
The full working script is in examples/03_naukri_apply.py.
How it works (architecture)
┌─────────────────────────────────────────────────────────────┐
│ YOUR AI AGENT │
│ (GPT-4, Claude, Llama, or any LLM with function-calling) │
│ │
│ Thinks in natural language: │
│ "Log in to LinkedIn and send 5 recruiters a message" │
└──────────────────────────┬───────────────────────────────────┘
│
│ Natural-language intent
▼
┌─────────────────────────────────────────────────────────────┐
│ mcpwright (Python) │
│ This library — the missing layer │
│ │
│ • Translates intent into MCP tool calls │
│ • Smart waits (waits for state, not DOM) │
│ • Real keyboard typing (React state updates) │
│ • Selector fallback (3+ strategies) │
│ • Auto-retry with backoff │
│ • Rate-limit aware pacing │
│ • Visual + DOM verification │
└──────────────────────────┬───────────────────────────────────┘
│
│ JSON-RPC over stdio
▼
┌─────────────────────────────────────────────────────────────┐
│ Playwright MCP Server (Microsoft) │
│ @playwright/mcp@latest — official MCP for Playwright │
│ │
│ Exposes 23 tools: navigate, click, type, screenshot, etc │
│ Handles all low-level browser control │
└──────────────────────────┬───────────────────────────────────┘
│
│ Chrome DevTools Protocol
▼
┌─────────────────────────────────────────────────────────────┐
│ YOUR CHROME BROWSER │
│ With your saved profile — stays logged in │
│ │
│ • Cookies persist across runs │
│ • Looks like a real user to websites │
│ • No fingerprinting or bot detection flags │
└─────────────────────────────────────────────────────────────┘
mcpwright is the layer that doesn't exist in the open-source market today. Playwright is great for tests. Playwright + MCP is great for AI agents. But it ships "raw" — every developer has to re-discover the React typing trick, the smart-wait pattern, the selector fallback. mcpwright packages all of that into a single, reusable library.
Why I built this
I'm a BBA grad who taught himself to code with AI. I built an AI agent (named James) to apply for jobs on my behalf. Every week, the agent would break on a different site: LinkedIn stopped responding to clicks, Naukri's React forms rejected the typed input, the test runs would hang on a slow page load.
I'd fix one thing, another would break. There was no library that handled the specific ways AI agents fail at browser automation — only test-automation libraries that humans write scripts for.
So I packaged every fix I'd learned into mcpwright. If you're building an AI agent that needs to browse the web, this should save you weeks of debugging.
— Raghav Modi (GitHub)
Cross-platform support
| Platform | Status | Notes |
|---|---|---|
| Windows 10/11 | ✅ Verified | Use npx.cmd from C:\nvm4w\nodejs\npx.cmd |
| WSL2 (Ubuntu) | ✅ Ready | Same Python code, just npx (no .cmd) |
| Linux native | ✅ Ready | Install Chromium: npx playwright install chromium |
| macOS | ✅ Ready | Works out of the box |
The only thing that changes between platforms is the path to npx and the path to your Chrome profile. mcpwright handles both.
See docs/cross-platform.md for details.
For developers
API
from mcpwright import browser_session, smart_wait, react_aware_type, retry
# Main entry: open a browser session
with browser_session(profile_path="<YOUR_PROFILE>") as (send, recv):
# send(msg) — send a JSON-RPC message
# recv(timeout) — wait for and return the response
...
# Helpers
smart_wait(send, recv, selector, timeout=20) # wait for element, not fixed sleep
react_aware_type(send, recv, selector, text) # type into a React-controlled input
retry(callable, max_attempts=3, delay=2) # exponential-backoff retry
The 23 MCP tools
See docs/mcp-tools.md for the full reference.
Workflows
| Task | Example |
|---|---|
| Send a LinkedIn message | examples/02_linkedin_message.py |
| Apply to Naukri jobs | examples/03_naukri_apply.py |
| Extract job listings | examples/04_job_extraction.py |
| Fill a generic form | examples/05_form_filler.py |
Documentation
docs/architecture.md— Deep dive into the 4 layersdocs/setup.md— Install on Windows / WSL2 / Linux / macOSdocs/workflows.md— Reusable patterns (LinkedIn, Naukri, generic)docs/resilience.md— Retry, smart-wait, fallback selectorsdocs/mcp-tools.md— All 23 MCP toolsdocs/cross-platform.md— Path differences, profile migrationdocs/pitfalls.md— 10 common failures and how to avoid them
Contributing
PRs welcome. The bar: does this make an AI agent's life easier? If yes, send it.
For major changes, open an issue first. For small fixes, just send the PR.
License
MIT © Raghav Modi. See LICENSE.
You can use this in commercial products, fork it, modify it, sell services on top of it — anything. Just keep the copyright notice.
Credits
Built on top of:
- Playwright — Microsoft's browser automation framework
- Model Context Protocol — Anthropic's standard for agent-tool communication
- @playwright/mcp — The official MCP server for Playwright
If this saved you time, star the repo ⭐. It helps other AI builders find it.
Metadata
Release files for mcpwright 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| mcpwright-0.1.1.tar.gz | 17.6 kB | Without provenance | Details for mcpwright-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| mcpwright-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for mcpwright-0.1.1-py3-none-any.whl |
Total release size: 29.6 kB
Release files / mcpwright-0.1.1.tar.gz
| Download URL | mcpwright-0.1.1.tar.gz |
|---|---|
| Size | 17.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
358a99e80d7e89f30ac4f1cd320b002324cc10d137b5085411dd5c1395af56fe
|
|
BLAKE2b-256 checksum How to use checksums |
fca12294c88aa5dbb63d4b85c4cb54040b70b6c2ede0ca126652a6baa34908bd
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Release files / mcpwright-0.1.1-py3-none-any.whl
| Download URL | mcpwright-0.1.1-py3-none-any.whl |
|---|---|
| Size | 12.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
6e0ae298e0dc4d0130a4f6c60be2125323f76324875289c18ed5755938a9f39a
|
|
BLAKE2b-256 checksum How to use checksums |
9ba10d8888f692b3e79639eada868005da895553f5828a559006bbb9af92a7f3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.11.15
|
Security for mcpwright 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.