The Problem
If you’re using Claude Code with the Playwright MCP server behind a (corporate) firewall or need to route browser automation through a proxy, you might encounter connection issues. The Playwright MCP server needs to be configured to use your proxy settings, but finding the right way to do this isn’t immediately obvious.
The Solution
The solution is surprisingly simple: add a --proxy-server flag to the Playwright MCP configuration in your Claude Code settings. Here’s how to do it step by step.
Step-by-Step Guide
1. Locate Your Claude Code Configuration File
Claude Code stores its configuration in a .claude.json file. The location depends on your operating system:
- macOS/Linux:
/Users/<your-username>/.claude.json - Windows:
C:\Users\<your-username>\.claude.json
This is your user-level configuration that applies to all your projects.
2. Edit the Configuration File
Open the .claude.json file in your favorite text editor. You’ll find a structure similar to this:
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": [
"@playwright/mcp@latest"
]
}
}
}3. Add the Proxy Configuration
Modify the playwright section by adding the --proxy-server flag to the args array:
{
"mcpServers": {
"playwright": {
"type": "stdio",
"command": "npx",
"args": [
"@playwright/mcp@latest",
"--proxy-server=http://127.0.0.1:7001"
]
}
}
}Replace http://127.0.0.1:7001 with your actual proxy server address and port.
4. Save and Restart
After saving the file, restart Claude Code for the changes to take effect. The Playwright MCP server will now route all browser traffic through your specified proxy.
Advanced Configuration Options
Bypassing Proxy for Certain Domains
If you need to bypass the proxy for internal sites or localhost, add the --proxy-bypass flag:
"args": [
"@playwright/mcp@latest",
"--proxy-server=http://127.0.0.1:7001",
"--proxy-bypass=localhost,127.0.0.1,.internal.company.com"
]Using SOCKS5 Proxy
For SOCKS5 proxies, use the appropriate protocol in the URL:
"args": [
"@playwright/mcp@latest",
"--proxy-server=socks5://127.0.0.1:7002"
]Other Useful Flags
You can combine the proxy configuration with other Playwright MCP flags:
"args": [
"@playwright/mcp@latest",
"--proxy-server=http://127.0.0.1:7001",
"--headless",
"--browser=chrome"
]Why This Approach Works
The --proxy-server flag is a built-in command-line option in the Playwright MCP server that directly configures the browser instance to use the specified proxy. This is:
- Simple: No need for separate configuration files
- Reliable: Officially supported by Playwright MCP
- Flexible: Works with HTTP, HTTPS, and SOCKS5 proxies
Troubleshooting
Verify Your Configuration
To check if your configuration is correct, look for any error messages when Claude Code starts the Playwright MCP server. If the proxy is misconfigured, you’ll see connection errors in the Claude Code logs.
Common Issues
- Proxy Authentication: If your proxy requires authentication, you’ll need to use a more complex configuration with a separate config file
- Wrong Proxy Address: Double-check your proxy address and port
Conclusion
Configuring Playwright MCP to work with a proxy in Claude Code is straightforward once you know where to look. By adding a single --proxy-server flag to your configuration, you can ensure all browser automation traffic routes through your proxy correctly.
This solution is clean, maintainable, and officially supported. No more connection issues or workarounds – just smooth browser automation through your proxy!