har-mcp

English | 简体中文

An MCP server for analyzing large HAR files with schema-less protobuf / gRPC decoding, built for reverse-engineering and traffic research workflows.

It turns huge, opaque HAR captures (full of binary protobuf bodies) into targeted, structured queries — so your AI agent no longer has to "drop out to Python" to decode a single field.

Why

Capture tools (Reqable, Charles, mitmproxy, …) export HAR. For apps that speak protobuf/gRPC (Google Play, gRPC services, …) those HAR files are large and their bodies are opaque binary. Existing options either truncate big bodies or force you into manual side-scripts.

har-mcp is different:

• No silent truncation. Bodies are stored in full. Large bodies return a sized preview by default and the whole payload on demand (full:true) or via structured decoding.
• Schema-less protobuf decoding. Bodies are decoded without any .proto — field numbers, wire types, nested messages, strings, bytes — so you can inspect obfuscated/proprietary protocols immediately.
• Any path, no lock-in. Every tool accepts an arbitrary .har path (or a registered name). No fixed working directory to configure.
• Scales to 100 MB+ HAR. Streaming index build + a split SQLite schema (slim metadata table vs. isolated body blobs) keep listing/filtering instant and memory flat.
• ID-addressed, Reqable-friendly. Entries are addressed by Reqable's own _id / _uid, mirroring the official Reqable MCP's filter → id → operate-by-id pattern.

Getting started

1. Install Bun

har-mcp runs on Bun (it uses the built-in bun:sqlite, so there are no native dependencies to compile).

# macOS / Linux
curl -fsSL https://bun.sh/install | bash
# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"

Verify with bun --version (requires ≥ 1.1).

2. Get har-mcp

Pick one:

• From source (recommended):

  git clone https://github.com/yynag/har-mcp.git
  cd har-mcp
  bun install
  

• Compiled JS from Releases: download index.js from the latest release — built by CI with all dependencies bundled, so you only need Bun to run it (bun /path/to/index.js).

3. Configure your MCP client

No directory to configure — you point at HAR files by path through the tools (see step 4).

opencode (opencode.jsonc):

"har": {
  "type": "local",
  "command": ["bun", "run", "/absolute/path/to/har-mcp/src/index.ts"],
  "enabled": true
}

Using the compiled release JS instead of source:

"har": {
  "type": "local",
  "command": ["bun", "/absolute/path/to/index.js"],
  "enabled": true
}

Claude Desktop / Cursor / any stdio client (claude_desktop_config.json / mcp.json):

{
  "mcpServers": {
    "har": {
      "command": "bun",
      "args": ["run", "/absolute/path/to/har-mcp/src/index.ts"]
    }
  }
}

Optionally set HAR_DB_PATH (env) to choose where the index database lives.

4. Load HARs and go

Load a single file or a whole directory, then query by ID:

har_index { "target": "/path/to/captures" }     # or a single /path/to/file.har
har_filter { "keyword": "acquire" }              # -> IDs
har_decode_body { "id": 254, "target": "request" }

Most tools' file parameter also accepts an arbitrary .har path directly — it is indexed on demand, so you can skip har_index entirely.

Loading & cleanup

• Load: har_index { target } where target is a .har file or a directory (indexes every *.har in it). har_files { dir } optionally scans a directory to register its files and always lists the current registry.
• Index = derived cache: HAR files are the source of truth. The SQLite index can be deleted and rebuilt at any time; cleanup never touches your HAR files.
• Auto-prune: har_files / har_index automatically drop indices whose HAR file no longer exists on disk, then VACUUM to reclaim space.
• Manual drop: har_forget { file } removes one file's index (by path or name) and reclaims space.

Configuration

Variable / flag	Description	Default
HAR_DB_PATH / --db	Index database path	<tmpdir>/har-mcp/index.db
HAR_PREVIEW_BYTES	Body preview size before truncation notice	8192
HAR_DECODE_MAX_DEPTH	Protobuf recursion depth	12
HAR_FILTER_LIMIT	Default result limit	100

Tools

Tool	Description
har_files	List indexed files (the registry); optionally scan a directory first. Auto-prunes missing files.
har_index	Build / rebuild the index. target = a .har file, a directory, or omit to re-check all registered files.
har_forget	Drop a file's index (by path or name) and reclaim space.
har_filter	Filter entries → returns compact rows with IDs (no bodies). file accepts an arbitrary path. Fast on huge HARs.
har_get_by_id	Fetch a full entry (headers + body) by Reqable ID. Binary → base64; preview unless full:true.
har_generate_curl	Generate a cURL command from an entry ID.
har_decode_body	Decode a body as schema-less protobuf (auto base64/gzip/gRPC). Optional path to focus a sub-field (e.g. 1.11).
har_diff	Field-level diff of two decoded bodies (great for "working request vs. my request").
har_search	Keyword search over url/host/headers (FTS) and optionally text bodies.

Typical workflow

1. har_index { target: "/path/to/captures" } → load.
2. har_filter { keyword: "acquire" } → get IDs of interest.
3. har_decode_body { id: 254, target: "request" } → inspect the protobuf.
4. har_diff { idA: 3, idB: 947, target: "request" } → see exactly which fields differ.
5. har_generate_curl { id: 3 } → reproduce a request.

How it works

Storage. Each HAR is streamed (stream-json) into a SQLite index the first time it is referenced:

• files — the registry of indexed HARs (path/name/size/status), keyed by absolute path.
• entries — slim, indexed metadata (method/host/path/status/kind/sizes). Filters scan only this table.
• bodies — headers + full body BLOBs, fetched only by ID. Never scanned during listing.
• entries_fts — FTS5 over url/host/path/headers for har_search (falls back to LIKE if unavailable).

Body classification. content.encoding == "base64" marks binary bodies. Because mimeType is often missing or wrong, bodies are re-classified by magic bytes: gzip (1f 8b), gRPC frame (00 + matching BE length), protobuf (low tag byte), image, text, binary.

Protobuf decoding. A schema-less wire-format decoder walks varint / fixed32 / fixed64 / length-delimited fields. A length-delimited value is rendered as a string when it is valid UTF-8 with no hard control characters; otherwise it is recursively tested as a nested message (strict full-buffer parse); otherwise as hex bytes. This cleanly separates text from sub-messages without a schema. gRPC bodies have their 5-byte frame header stripped (multi-frame supported); gzip is decompressed defensively. Depth, field-count and string-length limits keep output bounded.

IDs. id is Reqable's _id (human-friendly); uid is _uid (globally unique). If an id appears in multiple files (e.g. a capture exported twice), pass file (a path or name) to disambiguate; results carry a _note.

Development

bun install
bun run typecheck          # tsc --noEmit
bun run test:ci            # synthetic-fixture test: path indexing, prune, forget, decode (CI-safe)
bun run smoke              # store + decoder smoke test (set HAR_DIR to real HARs)
bun run smoke:mcp          # end-to-end MCP protocol test
bun run build:js           # bundle to dist/index.js
bun run build              # standalone binary

CI (.github/workflows/build.yml) runs typecheck + test:ci, bundles dist/index.js, uploads it as an artifact, and attaches it to a release on v* tags.

License

MIT — see LICENSE.