har2mcp

Turn an authorized browser network recording into an offline API exploration kit: observed endpoint documentation, a recorded-response client, and an MCP server for AI-assisted inspection.

Early alpha: 0.1.0a1. Live HTTP is intentionally unavailable in this release. This tool does not reconstruct a backend or prove that a captured API contract is complete. There are no claimed users, adoption metrics or sponsorship approvals.

Who is it for?

• Developers exploring an API they own or are authorized to inspect.

• Testers who need local recorded responses without calling the original service.

• MCP developers prototyping an integration from a synthetic or approved recording.

Related MCP server: Clarity MCP Server

Install from source

Requires Python 3.11+. No Claude subscription or API key is needed. The package is distributed from this GitHub repository; no PyPI publication is claimed.

git clone https://github.com/jaspreet9kaur/har2mcp.git
cd har2mcp
python -m venv .venv

Activate the virtual environment:

# Linux / macOS
. .venv/bin/activate

# Windows PowerShell: use its Python directly; no activation-policy changes needed
.venv\Scripts\python.exe -m pip install .
.venv\Scripts\python.exe -m har2mcp --help

On Linux/macOS, install with python -m pip install .. For the examples below, use the virtual environment's Python (or .venv\Scripts\python.exe on Windows). Installation downloads dependencies; processing a capture and replaying it are offline.

Try the synthetic example

python -m har2mcp inspect tests/fixtures/sample_api.synthetic.har --include-graphql
python -m har2mcp compile tests/fixtures/sample_api.synthetic.har --out demo-bundle --include-graphql
python -m har2mcp serve demo-bundle --mode cassette

Choose a new output directory each time. Compilation refuses an existing directory. The stdio server waits for an MCP client; it is not an HTTP website. Stop it with Ctrl+C when finished.

Generated files

The generated server depends on the installed har2mcp package. It is not a standalone executable. The TypeScript client accepts the records in cassette.json through its cassetteEntries option; it does not load files or contact a server automatically.

Connect an MCP client

For a client that accepts a stdio command configuration:

{
  "mcpServers": {
    "har2mcp-demo": {
      "command": "/absolute/path/to/har2mcp/.venv/bin/python",
      "args": ["-m", "har2mcp", "serve", "/absolute/path/to/demo-bundle", "--mode", "cassette"]
    }
  }
}

Replace both paths with your own; on Windows use the .venv\\Scripts\\python.exe path with JSON-escaped backslashes. Configuration layouts differ by client. Returned captured content is untrusted data, not instructions for the assistant to obey.

Replay and simulation

Default replay requires matching origin, method, tool, path, query and parsed request body. If no recorded request matches, it returns matched: false and a local 404 result. Repeated identical requests select the earliest recorded response. No live request is sent, and recorded POST/DELETE responses do not change server state.

--mode simulated-state is an optional, heuristic in-memory CRUD experiment. Every response is labeled simulated-in-memory. Its collection grouping is simplistic and does not reproduce backend authorization, persistence, nesting, validation or business rules. Use cassette mode when fidelity to recorded requests matters.

Other commands

python -m har2mcp sanitize approved.har --out sanitized.json
python -m har2mcp diff old.har new.har

An endpoint absent from a second capture is reported as unobserved, not proven deleted. Origins are kept distinct. Captures with conflicting method/path combinations across origins must be split before OpenAPI compilation; they are not silently overwritten.

Privacy and limits

Use synthetic data for shared examples. HAR files can contain session cookies, API keys, personal records, signed URLs and secrets embedded in paths, ordinary-looking strings or GraphQL text. Heuristic redaction removes known patterns and sensitive field names; it does not guarantee a shareable or anonymized artifact. Review every generated file before sharing. Never commit real captures or use privileged production sessions for demonstrations.

Input limits include 50 MiB per HAR, 5,000 exchanges, 2 MiB bodies, bounded JSON nesting and 32 path segments. These are parser bounds, not a hard memory guarantee on your machine. HTML, multipart, binary/base64 and unsupported bodies are withheld. Route and schema inference remain guesses from finite samples. Review SECURITY.md and the baseline review.

Tests and contribution

See CONTRIBUTING.md for the reproducible isolated checks. The CI container blocks network access during test/build execution, mounts source read-only, starts with an explicit environment and limits CPU, memory, processes, files and scratch disk. Image/dependency provisioning occurs separately with network access. A Python socket monkeypatch is not treated as OS isolation.

Open a bug report using a minimal synthetic fixture. Useful contributions include inference false-positive fixes, better sanitization tests and clearer examples. See the roadmap.

License and provenance

MIT; existing notices are preserved. The user's original local implementation was adapted for this public alpha. morluto/rea was a conceptual reference reported by that implementation; this publication does not claim a new upstream code audit or inherit another project's adoption. See provenance.