impersonate-mcp

An MCP server that lets AI agents (Claude Desktop, Claude Code, and other MCP clients) drive impersonate-proxy — switch TLS (JA3/JA4) and HTTP/2 fingerprints, User-Agent, spoofed client IP and upstream proxies, then verify what the server actually sees, all in one conversation.

Requires a running impersonate-proxy. This server is a stdio client for the proxy's management API (mgmt_listen, default http://127.0.0.1:8081). It does nothing on its own — start the proxy first (setup).

Intended for authorized security testing of WAF and bot-detection systems you own or have explicit permission to test.

Tools

Pass --read-only to hide every tool that changes settings (set_*). fetch_url stays, but only for GET / HEAD / OPTIONS without a body.

Related MCP server: OSINT Tools MCP Server

Install

From a release (.mcpb)

Each mcp-v* release carries one MCPB bundle per platform: impersonate-mcp_<version>_<os>_<arch>.mcpb for darwin / linux (arm64, amd64) and win32 (amd64). Download the one for your machine and open it in Claude Desktop (or drag it onto Settings → Extensions); it asks for the management API URL, the proxy's ca.crt and the read-only switch. Check the download against SHA256SUMS.txt from the same release. The bundles are not code-signed.

Releases are also published to the official MCP Registry as io.github.ytkoka/impersonate-mcp.

From source

git clone https://github.com/ytkoka/impersonate-proxy.git
cd impersonate-proxy
make build-mcp   # prints the binary's absolute path

This is a separate Go module — make build and the Docker image don't include it.

Configure

Claude Code

claude mcp add impersonate -- /path/to/impersonate-proxy/impersonate-mcp/impersonate-mcp \
  --ca-cert /path/to/impersonate-proxy/ca.crt

Claude Desktop

Add to claude_desktop_config.json (use absolute paths — Claude Desktop doesn't read your shell PATH):

{
  "mcpServers": {
    "impersonate": {
      "command": "/path/to/impersonate-proxy/impersonate-mcp/impersonate-mcp",
      "args": ["--ca-cert", "/path/to/impersonate-proxy/ca.crt"],
      "env": { "IMPERSONATE_MGMT_URL": "http://127.0.0.1:8081" }
    }
  }
}

If the file already has other keys or servers, add "impersonate" inside the existing mcpServers object rather than appending a second top-level { ... }.

Options

Security

The proxy's management API has no authentication. Keep mgmt_listen on loopback, and run this server locally over stdio only.

fetch_url always goes through the proxy and refuses loopback, private and link-local destinations (checking the host, every resolved address and each redirect hop). To limit it further, set fetch_allow_hosts in the proxy's config.yaml (or start the proxy with -fetch-allow-hosts a.com,b.com): only those hosts and their subdomains are reachable. get_config shows the list; no tool can change it. If the proxy's configuration can't be read, fetch_url refuses rather than fetching unrestricted. DNS rebinding between this server's lookup and the proxy's own lookup is not prevented.

Releasing

The version lives in two places that must match: version in main.go and version in mcpb/manifest.json. scripts/package-mcpb.sh refuses to build otherwise.

make package-mcpb                           # bundles + SHA256SUMS.txt in impersonate-mcp/dist/ (needs jq, zip)
git tag mcp-v0.1.0 && git push origin mcp-v0.1.0

Pushing a mcp-v* tag runs .github/workflows/release-mcp.yml: it tests, builds the bundles, creates the GitHub Release, then publishes server.json (generated from server.template.json and the release's checksums) to the MCP Registry using GitHub OIDC — no secret is needed, and the io.github.ytkoka/ name is allowed because the repository owner is ytkoka. If only the registry step fails, re-run it with the workflow's manual trigger and the existing tag. A published registry version cannot be changed, so a fix needs a new version.

License

MIT — see the repository root.