Proxy Browser — MCP Server

Proxy Browser — MCP Server

An MCP server that lets Claude browse the web and makeGET / POST / PUT requests while looking like a real Chrome browser at the networklayer — 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 fingerprintyour TLS handshake (JA3/JA4) and HTTP/2 frame ordering — a stock Python HTTP clientis instantly identifiable as a bot no matter what User-Agent header it sends.

This server uses curl_cffi, which driveslibcurl with a real Chrome TLS + HTTP/2 fingerprint. The connection itself looks likeChrome — verified against tls.peet.ws (JA4 t13d1516h2, Chrome's Akamai HTTP/2fingerprint, 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 theright 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 usingforward 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_cffidoes 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 JSchallenge, curl_cffi alone can't run it. A headless-browser fallback can be added laterif a specific site demands it.
• Respect Terms of Service and rate limits. This tool is for legitimate automation andresearch; 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).