# har-mcp

**Professional MCP server for HAR (HTTP Archive) network captures.**

Fast • Safe • AI-first • Zero configuration

Point an AI agent at a `.har` file and let it extract endpoints, detect GraphQL, hunt leaked secrets, group traffic by domain, surface web issues, export cURL/Postman, compare captures, and generate reports.

## Features

- ⚡ Fast cached HAR loading
- 🤖 AI-first MCP tools
- 🔍 API & GraphQL discovery
- 🔐 Secret detection
- 📊 Timeline & dependency analysis
- 📦 OpenAPI & Postman export
- 💻 cURL and code generation
- 🛡 Automatic backups before modifications

## Install

```bash
# via npx (no install)
npx har-mcp

# or globally
npm install -g har-mcp
har-mcp
```

Requires Node.js >= 18. No build step. ESM-only.

## Quick Start

Open any MCP-compatible client and ask:

- "Summarize this HAR."
- "Find leaked secrets."
- "Export all GraphQL requests to Postman."
- "Generate OpenAPI from this capture."
- "Show slow requests over 2 seconds."

## Supported Formats

Supports standard HAR 1.2 exports from:

- Chrome DevTools
- Edge
- Firefox
- Reqable
- Charles Proxy
- Fiddler
- Proxyman
- HTTP Toolkit
- mitmproxy

## Why har-mcp?

| Feature | har-mcp |
|---------|---------|
| GraphQL detection | ✅ |
| Secret scanning | ✅ |
| OpenAPI generation | ✅ |
| Postman export | ✅ |
| Code generation | ✅ |
| MCP native | ✅ |
| AI optimized | ✅ |

## Example

User:

> Find Bearer tokens.

Agent:

```
> workspace(har_path="capture.har")
{
  "log": { "entries": 1247, ... }
}

> find_secrets(har_path="capture.har")
Found 1 potential secret(s) (values masked)

> get_request(har_path="capture.har", index=42)
Authorization: Bearer eyJhbGciOi...

> generate_code(har_path="capture.har", index=42, language="shell", framework="curl")
curl -X GET https://api.example.com/...
```

## How It Works

1. **Agent-driven analysis** — MCP clients (Claude Desktop, Cursor, VS Code, Kilo) call tools over stdio.
2. **Fast file access** — HAR files are cached in memory by `path + size + mtimeMs`. A persistent index in `~/.cache/har/index.json` stores precomputed workspace stats.
3. **Smart tool routing** — `recommend_tool(goal)` and `help(tool)` guide agents to the right workflow.
4. **Safe mutations** — destructive tools (`delete_host_requests`, `delete_request`) write `.bak` backups to `~/.cache/har/backups/` before modifying files.

## Capabilities

| Category | Tools |
|----------|-------|
| **Discovery** | `extract_endpoints`, `analyze_api`, `get_domains`, `detect_graphql`, `analyze_graphql` |
| **Inspection** | `list_requests`, `get_request`, `find_headers`, `find_cookies`, `search_requests` |
| **Analysis** | `har_summary`, `describe_har`, `group_by_domain`, `group_by_host`, `find_duplicates`, `timeline`, `dependency_tree` |
| **Security** | `find_secrets`, `detect_issues` |
| **Export** | `generate_code`, `export_postman`, `generate_openapi`, `generate_report`, `compare_har` |
| **Maintenance** | `delete_request`, `delete_host_requests` |
| **Agent Help** | `help`, `recommend_tool` |

## AI Workflow

Recommended order for agents analyzing a HAR file:

1. `workspace` — understand the capture shape (entries, hosts, domains, special protocols).
2. `describe_har` — get a plain-English overview.
3. `detect_issues` / `find_secrets` — surface problems and leaked credentials.
4. `group_by_host` / `extract_endpoints` — narrow scope before deep inspection.
5. `get_request` / `search_requests` — inspect specific requests.
6. `export_postman` / `generate_openapi` / `generate_code` — export or replay findings.

Use `help(tool='...')` for detailed arguments and examples, and `recommend_tool(goal='...')` to discover the right tool for a task.

## AI-Friendly

The server is designed for language models:

- **Deterministic output** — same input always returns same output.
- **Machine-readable** — structured text, JSON, and markdown.
- **Predictable schema** — Zod-validated arguments and return types.
- **Token efficient** — compact output with optional truncation.
- **Self-documenting** — `help()` and `recommend_tool()` let agents discover capabilities without external docs.

## Output Examples

### detect_graphql


Detected 3 GraphQL operation(s)

| Operation | Type | Method | Status | Errors |
|-----------|------|--------|--------|--------|
| Login | query | POST | 200 | 0 |
| RefreshToken | mutation | POST | 200 | 0 |
| Me | query | POST | 200 | 0 |


### find_secrets


Found 1 potential secret(s) (values masked)

| Type | Where | Location | Value |
|------|-------|----------|-------|
| bearer | authorization | https://api.example.com | eyJhbG... |


### timeline (mermaid)

```
gantt
    title Request Timeline
    dateFormat X
    section Auth
    Login :0, 120
    section API
    GetUser :150, 300
```
## Performance

- **In-memory cache** — HAR files cached by `path + size + mtimeMs` key.
- **Incremental index** — `~/.cache/har/index.json` stores precomputed workspace stats.
- **Lazy formatting** — request details are formatted only when requested.
- **Zero-copy parsing** — JSON parsed once per cache miss.

## Security

- HAR files are processed **entirely locally**.
- No network requests are made to external services.
- No telemetry, analytics, or phone-home.
- No external APIs contacted.
- Secrets are **masked** in tool output.

## Supported Code Generation

`generate_code` supports:

- **C** (libcurl)
- **C#** (HttpClient, RestSharp)
- **Dart** (Dio)
- **Go** (native net/http)
- **Java** (AsyncHttp, HttpClient, OkHttp, Unirest)
- **JavaScript** (axios, fetch, jQuery, XHR)
- **Kotlin** (OkHttp)
- **Node.js** (axios, fetch, native, request, Unirest)
- **PHP** (curl, Guzzle)
- **Python** (http.client, Requests)
- **Shell** (curl)

## Supported MCP Clients

- Claude Desktop
- Cursor
- VS Code
- Kilo
- Cline
- Windsurf
- Roo Code
- Any MCP-compatible client

## Usage

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "har-mcp": {
      "command": "npx",
      "args": ["har-mcp"]
    }
  }
}
```

### Cursor / VS Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "har-mcp": {
      "command": "npx",
      "args": ["har-mcp"]
    }
  }
}
```

## Filtering

`list_requests`, `group_by_host`, and `search_requests` accept filters:

- `session`: `http` | `https` | `websocket` | `sse`
- `protocol`: `http1` | `http2` | `http3`
- `mime`: `json` | `xml` | `text` | `html` | `js` | `image` | `media` | `binary`
- `code`: `1xx` | `2xx` | `3xx` | `4xx` | `5xx`

`search_requests` also supports `case_sensitive` and `regex` modes.

## Goal → Tool Reference

| Goal | Tool |
|------|------|
| Overview | `workspace` |
| Find APIs | `extract_endpoints` |
| GraphQL | `detect_graphql` |
| Security | `find_secrets` |
| Performance | `timeline` |
| Debug request | `get_request` |
| Export Postman | `export_postman` |
| Generate OpenAPI | `generate_openapi` |
| Replay request | `generate_code` |
| Generate code | `generate_code` |

## Architecture

- **Entry**: `src/index.js` → `main()` in `src/server.js` → `createServer()`
- **Tools**: 28 MCP tools registered in `src/server.js` with Zod schemas and `wrap()` error handling
- **Modules**:
  - `har.js` — file loading, HAR helpers, cache, index
  - `analyze.js` — list, filter, group, detect issues, secrets, GraphQL
  - `request.js` — request formatting (summary, raw, headers, cookies, body)
  - `export.js` — Postman export, markdown/HTML reports
  - `snippets.js` — code generation (11 languages, ~15 frameworks)
  - `compare.js` — HAR diffing
  - `insights.js` — timeline, dependency tree, OpenAPI, describe

## Cache / Work Directory

- Cache dir: `~/.cache/har/`
- Backups: `~/.cache/har/backups/`
- Reports: `~/.cache/har/reports/`
- Index: `~/.cache/har/index.json`

## Tool Reference

### workspace
Return metadata about the loaded HAR file: entry count, hosts, domains, GraphQL/WebSocket/SSE presence, start time, and total duration.

### har_summary
Quick overview: request count, domains, endpoints, GraphQL, secrets, and issue counts.

### describe_har
Generate a natural-language description of the HAR file contents.

### list_requests
List captured requests with filtering by host, session, protocol, MIME, and status code.

### get_request
Show a single request in detail: summary, raw, query, body, headers, and cookies.

### find_headers
Find all request/response headers with a given name across the HAR.

### find_cookies
Find cookies in the HAR, optionally filtered by name.

### search_requests
Search by keyword or regex in URL, request body, response body, or raw entry.

### get_domains
List all domains seen in the HAR with request counts.

### analyze_api
Analyze the API surface of one domain: endpoints, status codes, auth, and JSON body structure.

### extract_endpoints
Extract and cluster unique API endpoints (method + path, IDs normalized to `:id`).

### detect_graphql
Detect GraphQL operations and surface errors.

### analyze_graphql
Analyze GraphQL operations by type: queries, mutations, subscriptions.

### find_secrets
Hunt for leaked secrets: Bearer tokens, JWTs, API keys, AWS/Stripe/GitHub tokens, private keys.

### group_by_domain
Group requests by domain with counts, methods, bytes, and timings.

### group_by_host
Group requests by host:port with request counts and filters.

### find_duplicates
Find duplicate requests (same method + URL) for de-noising.

### detect_issues
Detect common web problems: 4xx/5xx errors, redirects, CORS, cache, mixed content, missing security headers, large/slow responses.

### timeline
Show a chronological timeline of requests with relative timings and optional mermaid Gantt chart.

### dependency_tree
Build a best-effort dependency tree from Referer headers.

### generate_code
Generate ready-to-run code snippets. Supports 11 languages and multiple frameworks, including `language="shell"` + `framework="curl"` for cURL commands.

### export_postman
Export the HAR as a Postman Collection (v2.1) JSON.

### generate_openapi
Generate a basic OpenAPI 3.1.0 spec from the HAR's API endpoints.

### generate_report
Generate a human-readable analysis report (markdown or HTML).

### compare_har
Compare two HAR captures: added/removed/changed endpoints, new cookies, new secrets.

### delete_request
Remove a single request by index, writing a `.bak` backup first.

### delete_host_requests
Remove all requests for a given host, writing a `.bak` backup first.

### help
Return detailed help for any tool: args, returns, related tools, and examples.

### recommend_tool
Suggest tools based on a natural-language goal.

## FAQ

**Does this modify my HAR?**

No. Only `delete_request` and `delete_host_requests` modify files, and they automatically create `.bak` backups in `~/.cache/har/backups/`.

**Where are backups stored?**

`~/.cache/har/backups/` by default. The original `.har` file is never overwritten without a backup.

**Is my data sent anywhere?**

No. Everything runs locally. No telemetry, no analytics, no external APIs.

**Which HAR versions are supported?**

HAR 1.2, as exported by Chrome, Edge, Firefox, and most proxy tools.

**How do I update?**

```bash
npm update -g har-mcp
```

## License

MIT