Proxy Browser — MCP Server

An MCP server that lets Claude browse the web and make GET / POST / PUT requests while looking like a real Chrome browser at the network layer — so you don't get anti-bot flagged on sites like AliExpress.

• Real Chrome TLS/HTTP2 fingerprint (via curl_cffi), not just a spoofed User-Agent
• Persistent cookie session — multi-step browsing looks like one continuous browser
• Token-efficient output — HTML is cleaned into markdown by default (raw available)
• Optional upstream proxy — plug in a residential/rotating proxy for IP rotation
• GET, POST, PUT with form or JSON bodies

---

Why not just requests + a Chrome User-Agent?

Because a UA string fools nobody serious. Cloudflare, Akamai, and AliExpress fingerprint your TLS handshake (JA3/JA4) and HTTP/2 frame ordering — a stock Python HTTP client is instantly identifiable as a bot no matter what User-Agent header it sends.

This server uses curl_cffi, which drives libcurl with a real Chrome TLS + HTTP/2 fingerprint. The connection itself looks like Chrome — verified against tls.peet.ws (JA4 t13d1516h2, Chrome's Akamai HTTP/2 fingerprint, over h2).

---

Requirements

• Python 3.9+ (developed/tested on 3.11, Windows 11)

• pip

• Claude Code CLI (to consume the MCP server)

• Python packages (installed via requirements.txt):

  Package	Role
  mcp	Official MCP Python SDK (FastMCP server)
  curl_cffi	Chrome TLS/HTTP2 impersonation engine (bundled libcurl)
  trafilatura	Main-content extraction → markdown (token-efficient)
  beautifulsoup4	Full-page DOM cleanup
  markdownify	HTML → markdown conversion

curl_cffi ships its own libcurl build, so there is no external C dependency to install.

---

Installation

# 1. Clone the repo
git clone https://github.com/nullsection/headless-proxy-mcp.git
cd headless-proxy-mcp

# 2. (recommended) create a virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1        # PowerShell
# source .venv/bin/activate         # macOS/Linux

# 3. Install dependencies
python -m pip install -r requirements.txt

---

Setup — register with Claude Code

# User scope = available in all your projects
claude mcp add -s user proxy-browser -- python C:/path/to/headless-proxy-mcp/proxy_browser_server.py

# Verify
claude mcp get proxy-browser        # should show: Status: Connected

Use forward slashes in the path — a backslash path can be mangled by the shell.

To pass configuration (e.g. a proxy), add -e flags:

claude mcp add -s user proxy-browser \
  -e PROXY_URL=http://user:pass@host:port \
  -e IMPERSONATE=chrome124 \
  -- python C:/path/to/headless-proxy-mcp/proxy_browser_server.py

Restart Claude Code after registering so it loads the server.

---

Usage

Once registered and restarted, just ask Claude in natural language — e.g. "browse aliexpress for usb cables and summarize the top results." Claude selects the right tool automatically.

Tools

Tool	Description
browse	HTTP GET a URL (read/browse pages & APIs).
http_post	HTTP POST with form data or json body.
http_put	HTTP PUT with form data or json body.
session_reset	Clear cookies / start a fresh browsing identity.
session_info	Show impersonation target, proxy, and current cookies (debugging).

Parameters

• url — full URL including http:// or https://.
• extract — how the body is returned:
  • "auto" (default) — main content as markdown (best for pages)
  • "full" — the whole page converted to markdown
  • "text" — plain text only
  • "raw" — exact HTML / response bytes
• headers — optional extra request headers (merged over sane Chrome defaults).
• proxy — optional per-request proxy URL (overrides PROXY_URL for that call).
• timeout — request timeout in seconds (default 30).
• data / json (POST/PUT only) — form fields or a JSON body (use one).

---

Configuration

Set via environment variables (or -e flags at registration). See .env.example.

Variable	Default	Description
IMPERSONATE	chrome124	Chrome build to mimic (e.g. chrome116, chrome124, chrome131).
PROXY_URL	(empty)	Upstream proxy: http://user:pass@host:port or socks5://host:port. Empty = direct.
MAX_CHARS	60000	Max body characters returned to Claude (protects the context window).
PER_HOST_DELAY	0	Minimum seconds between requests to the same host (politeness / anti-flag).

---

Troubleshooting

• Failed to connect — the path was likely mangled by backslashes. Re-add using forward slashes (see setup above), and confirm python is on your PATH.
• Server connects but a site still blocks you — you're probably being flagged by IP, not fingerprint. Set PROXY_URL to a residential/rotating proxy and raise PER_HOST_DELAY.
• Page comes back blank / missing content — the site renders via JavaScript. curl_cffi does not execute JS (see Limitations).
• Response truncated — raise MAX_CHARS, or request a tighter extract mode.

---

Limitations

• No JavaScript execution. If a page renders entirely via JS or throws an interactive JS challenge, curl_cffi alone can't run it. A headless-browser fallback can be added later if a specific site demands it.
• Respect Terms of Service and rate limits. This tool is for legitimate automation and research; use PER_HOST_DELAY to stay polite, and don't hammer sites.

---

Project layout

headless-proxy-mcp/
├── proxy_browser_server.py   # the MCP server (all logic)
├── requirements.txt          # Python dependencies
├── .env.example              # configuration reference
├── .gitignore
└── README.md

License

MIT (or your preference).