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).

Related MCP server: gotham-browser

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

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.

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).