Content
<h1 align="center">reqable-mcp</h1>
<p align="center">
<strong>Bring Reqable's captured HTTP traffic into your Claude Code conversation.</strong><br/>
Read-only · zero-touch · no Reqable Pro required.
</p>
<p align="center">
<a href="#"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg" alt="Python 3.10+"></a>
<a href="#"><img src="https://img.shields.io/badge/platform-macOS-lightgrey.svg" alt="macOS"></a>
<a href="#"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="MIT"></a>
<a href="#"><img src="https://img.shields.io/badge/MCP-1.27%2B-orange.svg" alt="MCP 1.27+"></a>
<a href="#"><img src="https://img.shields.io/badge/tests-111%20passed-brightgreen.svg" alt="111 tests"></a>
<a href="#"><img src="https://img.shields.io/badge/status-alpha-yellow.svg" alt="alpha"></a>
</p>
---
## What it does
[Reqable](https://reqable.com) is a native macOS HTTP/HTTPS debugging proxy. Every request it captures lands in a local ObjectBox/LMDB database. **`reqable-mcp` is a read-only [Model Context Protocol](https://modelcontextprotocol.io) server that hands that traffic to Claude Code** so you can ask the AI things like:
> *"List the last 10 requests Chrome sent to `api.target.com`. Tell me which fields are dynamic per request — those are likely the encryption signature."*
>
> *"Wait for the next POST to `/login`, then decode the JWT in the response and show its claims."*
>
> *"Diff request `0e65fcea-...` and `f06fdfd2-...` to figure out what changed in the auth flow."*
Reqable keeps doing what Reqable does best (mitm, GUI, breakpoints, mocks). This project just adds an **AI-readable view** on top of its existing data — no replacement, no overlap.
> [!IMPORTANT]
> **No second proxy layer while in use.** Reqable is already your system proxy when capturing. Stacking another proxy (Clash, Surge, SwitchyOmega…) on top creates a request loop that will pollute capture data and may deadlock. The daemon enforces this in three places — see [Proxy loop guard](#proxy-loop-guard) below.
---
## Features
- 🪟 **Zero-touch on Reqable** — no config files modified, no scripts enabled, no Pro required (for the MVP feature set).
- 📚 **Reads existing captures** — every request Reqable has already recorded is queryable, including before this tool was installed.
- 🔌 **Live updates** — a 250 ms LMDB poller streams new captures into a local SQLite cache as Reqable writes them.
- 🧰 **13 MCP tools** — query, search, wait, diff, decode, transform; full list [below](#available-tools).
- 🛡️ **Proxy-loop hardened** — env scrub + `scutil --proxy` detection + zero HTTP-client imports anywhere in the codebase.
- ⚡ **Pure-Python, single process** — Claude Code spawns it, Claude Code disconnects, it goes away. No launchd, no daemon socket, no orphan state.
- 🔍 **Self-describing schema** — ObjectBox entity layout is parsed straight out of LMDB metadata; no `.fbs` files shipped, no version pinning.
---
## Quick start
```bash
git clone https://github.com/Wanghaibo10/Reqable-Mcp.git
cd Reqable-Mcp
./install.sh
# restart Claude Code, then in any chat:
# "Use list_recent to show me the 5 newest captures."
```
Sanity-check from the shell at any time:
```bash
.venv/bin/reqable-mcp status
```
---
## Installation
### Requirements
- macOS (only platform Reqable supports today)
- Python ≥ 3.10 — `brew install python@3.13` if you need it
- [Reqable](https://reqable.com) installed and used at least once
- Claude Code (the agent that talks to MCP servers)
### One-line install
```bash
./install.sh
```
What it does, in order:
1. Picks the newest Python ≥ 3.10 on `$PATH`
2. Creates `.venv/` and installs the package in editable mode
3. Creates `~/.reqable-mcp/` with `0700` permissions (cache, logs)
4. Adds the server entry to `~/.claude/mcp.json`
What it does **not** do:
- Touch any file under `~/Library/Application Support/com.reqable.macosx/`
- Install a launchd plist or any background service
- Require root or `sudo`
### Manual install
<details>
<summary>If you'd rather wire things up yourself</summary>
```bash
python3.13 -m venv .venv
.venv/bin/pip install -e .
mkdir -m 700 -p ~/.reqable-mcp
```
Then add this entry to `~/.claude/mcp.json` (create the file if missing):
```json
{
"mcpServers": {
"reqable": {
"command": "/absolute/path/to/.venv/bin/reqable-mcp",
"args": ["serve"]
}
}
}
```
Restart Claude Code. `/mcp` should list `reqable` as connected.
</details>
### Uninstall
```bash
./uninstall.sh
```
Removes only `~/.reqable-mcp/` and the `reqable` entry in `~/.claude/mcp.json`. Reqable's own data and configuration are untouched.
---
## Available tools
| Tool | Tier | What it does |
| --- | --- | --- |
| `list_recent` | query | Most recent captures, filterable by `host` / `method` / `status` / `app`. |
| `get_request` | query | One capture in full — headers + body (body fetched on demand). |
| `search_url` | query | URL substring or regex search. |
| `search_body` | query | Full-text search across request/response body content. |
| `to_curl` | query | Render a capture as a runnable `curl` command (auto-adds `--noproxy '*'`). |
| `list_apps_seen` | query | Recently captured apps (Chrome / Safari / native binaries). |
| `stats` | query | Host / method / status distribution over a window. |
| `diff_requests` | query | Field-level diff between two captures (metadata + headers). |
| `wait_for` | sync | Block until the next matching capture appears (or until timeout). |
| `find_dynamic_fields` | reverse | Detect fields that vary request-to-request — likely tokens / signatures. |
| `decode_jwt` | reverse | Decode a JWT, or extract one from a captured request's headers. |
| `extract_auth` | reverse | List Authorization / Cookie / `X-*-Token` values seen on a host. |
| `status` | meta | Daemon + LMDB schema + sync counters (also a CLI command). |
Each tool's docstring is what Claude Code shows when it lists tools — keep that in mind if you hack on them.
---
## Usage examples
Once installed, just talk to Claude Code. Every interaction below is what an actual conversation looks like — Claude calls the tool itself based on intent.
### Watch what your browser is doing
> **You:** What URLs has Chrome hit in the last 5 minutes? Group by host.
>
> **Claude** *(uses `list_apps_seen` then `list_recent` filtered by app)*: In the last 5 min Chrome made 168 requests across these hosts: `www.vipdlt.com` (36), `outlook.live.com` (23), `s.c-ctrip.com` (14)…
### Find the encryption parameter
> **You:** I'm reverse-engineering `target-api.com`. Which request fields look like they're freshly generated each call?
>
> **Claude** *(uses `find_dynamic_fields(host="target-api.com")`)*: Across 20 sampled requests these vary on every call — likely signatures / nonces:
>
> - `header:x-bm-sensor-data` (long base64)
> - `query:_t` (millisecond timestamps)
> - `body.requestId` (UUIDs)
>
> Stable across all 20: `header:host`, `header:user-agent`, `query:appid`.
### Wait for the user, then analyze
> **You:** I'm about to click "checkout" — wait for the order POST and tell me what auth headers it carries.
>
> **Claude** *(uses `wait_for(host="api.shop.com", method="POST", path_pattern="/orders", timeout_seconds=120)` then `extract_auth`)*: Got it — capture `b51c72ac-…`. The request carried `Authorization: Bearer eyJhbGciOiJIUz…`, plus four cookies: `session_id`, `csrf`, `device_fp`, `cart_token`. The Bearer is a JWT — decoded payload has `sub: 4892731`, `exp` in 14 minutes.
### Reproduce a request from the shell
> **You:** Give me a curl that reproduces the latest call to `/api/v2/quote`.
>
> **Claude** *(uses `search_url("/api/v2/quote", limit=1)` → `to_curl`)*:
>
> ```bash
> curl --noproxy '*' -X POST \
> -H 'host: api.example.com' \
> -H 'authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6Ikp…' \
> -H 'content-type: application/json' \
> --data-raw '{"hotelId":12345,"checkin":"2026-05-01"}' \
> 'https://api.example.com/api/v2/quote'
> ```
---
## How it works
```
[browser / app]
│
▼
[Reqable mitm proxy] (Reqable.app — unchanged)
│
├──▶ [box/data.mdb] ◀── LMDB poller (250 ms, idle backoff)
│ (ObjectBox: metadata)
│
└──▶ [capture/{conn}-{sess}- ◀── Body source (read on demand)
{req_raw|res-raw|res-extract}-body.reqable]
┌─────────────── reqable-mcp serve (single process) ───────────────┐
│ proxy_guard env scrub + scutil --proxy detection │
│ LmdbSource FlatBuffers parse, base64+gzip+json decode │
│ BodySource capture/ file lookup by (conn_ts, conn_id, sid)│
│ Database SQLite WAL + FTS5 — metadata index only │
│ WaitQueue threading.Event broadcast for wait_for │
│ FastMCP stdio JSON-RPC, 13 tools registered │
└──────────────────────────────┬──────────────────────────────────┘
│ stdio
▼
[Claude Code]
```
**Key design choices** (see [`.spec/reqable-mcp/spec.md`](.spec/reqable-mcp/spec.md) for full rationale):
- **Truth lives in Reqable.** Our SQLite is a queryable cache; bodies are never copied — they stay in `capture/*.reqable`.
- **Schema is self-describing.** ObjectBox encodes its entity layout *into* the LMDB. We parse that, so Reqable adding fields doesn't break us.
- **Single process.** Claude Code launches `reqable-mcp serve`, the daemon lives only as long as that stdio session. Cold-start ≈ 250 ms.
- **No HTTP clients anywhere.** A test in CI greps the source tree to keep `requests`/`urllib3`/`aiohttp`/`httpx` out — they'd inherit env-driven proxy config and break the loop guard.
---
## Proxy loop guard
> [!CAUTION]
> Reqable as system proxy is fine. **Any second proxy on top is not.**
The daemon enforces this on three layers:
| Layer | Mechanism |
| --- | --- |
| **L1 — process env** | `scrub_env()` deletes every `*_PROXY` variable on startup and sets `NO_PROXY=*`. |
| **L2 — system proxy detection** | `scutil --proxy` is parsed at startup; non-loopback proxies emit a stderr warning. Set `REQABLE_MCP_STRICT_PROXY=1` to exit instead. |
| **L3 — code review** | The codebase contains zero imports of `requests` / `urllib3` / `aiohttp` / `httpx` — `tests/test_e2e.py::test_no_http_clients_imported` greps the source tree to enforce this on every test run. |
---
## Configuration
### Environment variables
| Variable | Default | Effect |
| --- | --- | --- |
| `REQABLE_MCP_STRICT_PROXY` | `0` | When `1`, exit with code 2 if a non-loopback system proxy is active at startup. |
### Paths
| Path | Purpose |
| --- | --- |
| `~/.reqable-mcp/cache.db` | SQLite metadata index (WAL mode). Safe to delete; rebuilt on next run. |
| `~/.reqable-mcp/daemon.log` | Daemon stderr (verbosity controlled by `--log-level`). |
| `~/.reqable-mcp/state.json` | Future use; currently unused. |
| `~/Library/Application Support/com.reqable.macosx/box/` | Reqable LMDB. Read-only. |
| `~/Library/Application Support/com.reqable.macosx/capture/` | Reqable body files. Read-only. |
### CLI commands
```text
reqable-mcp serve # MCP stdio server (Claude Code spawns this)
reqable-mcp status # Daemon snapshot as JSON, then exit
reqable-mcp install-help # Print MCP registration JSON
reqable-mcp --version
reqable-mcp --help
```
---
## Compatibility
| | Tested |
| --- | --- |
| macOS | 14, 15 |
| Reqable | **3.0.40** (April 2026) |
| Python | 3.10 / 3.11 / 3.12 / 3.13 |
| MCP SDK | 1.27.0 |
ObjectBox schema is parsed at runtime, so additive changes (new fields) are tolerated automatically. Breaking changes (renamed fields, new `dbData` envelope) require updating the projection in `lmdb_source.py`. The decoder is fail-safe: any individual record that won't decode is logged and skipped, never crashes the daemon.
This project does **not** support mitmproxy / Charles / Proxyman — those use different storage formats and would each need their own source module.
---
## Development
```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest # 111 tests; integration ones skip if no Reqable LMDB
.venv/bin/ruff check src/ tests/
.venv/bin/mypy src/
```
The repository layout:
```
.
├── .spec/reqable-mcp/ # Specification: read this before changing things
│ ├── spec.md # Requirements + design decisions + data model
│ ├── tasks.md # Module-by-module task plan
│ └── checklist.md # Acceptance checklist
├── src/reqable_mcp/
│ ├── proxy_guard.py # L1+L2 of the proxy guard
│ ├── paths.py # Filesystem path resolution
│ ├── db.py + schema.sql # SQLite cache layer
│ ├── wait_queue.py # Broadcast wait queue (threading.Event)
│ ├── daemon.py # Component composition
│ ├── mcp_server.py # FastMCP stdio entry
│ ├── __main__.py # `reqable-mcp` CLI dispatch
│ ├── sources/
│ │ ├── flatbuffers_reader.py # No-schema FB parser (stdlib only)
│ │ ├── objectbox_meta.py # ObjectBox entity introspection
│ │ ├── lmdb_source.py # 250 ms poller + decoder
│ │ └── body_source.py # capture/ file reader
│ └── tools/
│ ├── query.py # 8 query tools
│ ├── wait.py # wait_for
│ └── analysis.py # JWT / dynamic-fields / auth extraction
├── tests/ # 111 tests (unit + integration)
├── install.sh / uninstall.sh
└── pyproject.toml
```
Integration tests use a `real_lmdb_required` fixture that resolves to your local Reqable LMDB if one exists; otherwise they skip cleanly. Pure-logic tests have no such requirement.
---
## Limitations
- **macOS only.** Reqable is macOS-only at the time of writing.
- **Body sometimes missing.** Reqable doesn't keep every body forever — `capture/` files can be purged by Reqable. The tools surface `body_status: "unavailable"` in that case.
- **CONNECT tunnels.** TLS-handshake-only entries (no decrypted body) come through with `method=CONNECT` and limited metadata.
- **No write-back.** This is a read-only view. Tagging requests, mocking, modifying — that's [Phase 2](#roadmap).
---
## Roadmap
The MVP covers query, search, wait, and analysis. Two future phases extend into write-back territory:
- **Phase 2 — UI annotations + traffic modification.** `tag_pattern` / `comment_request` to highlight captures in Reqable's UI, plus `mock_response` / `block` / `replace_body`. Requires Reqable Pro (the script feature) and writing to `config/capture_config`'s `scriptConfig`. Entry condition: a week of MVP daily-use without daemon crashes, plus three concrete write-back use cases.
- **Phase 3 — Export + replay.** `dump_body`, `export_har`, `replay_request(uid, modifications)`.
---
## Acknowledgments
- [Reqable](https://reqable.com) — the actual hard work
- [Anthropic](https://www.anthropic.com) — Model Context Protocol and Claude Code
- [ObjectBox](https://objectbox.io) — for keeping their on-disk layout legible enough that we never had to ship an `.fbs` file
---
## License
[MIT](LICENSE)
---
<details>
<summary>简体中文摘要</summary>
`reqable-mcp` 把 Reqable 抓到的 HTTP/HTTPS 流量,通过 [Model Context Protocol](https://modelcontextprotocol.io) 只读地暴露给 Claude Code。
- ✅ 零侵入(不改 Reqable 任何文件、无需 Pro)
- ✅ 13 个工具(查询 / 搜索 / 等待 / 逆向辅助)
- ✅ 防代理回环(进程级 ENV scrub + 系统代理检测 + 代码层面禁 HTTP 客户端)
- ✅ 单进程(Claude Code 启动它,关闭它,仅此而已)
**安装:** `./install.sh`,然后重启 Claude Code。
**强约束:** Reqable 抓包时本身就是系统代理,所以**不要再叠第二层代理**(Clash / Surge 等),否则会形成回环。
详细中文版设计文档见 [`.spec/reqable-mcp/spec.md`](.spec/reqable-mcp/spec.md)(需求 + 架构 + 数据模型 + 决策追溯)。
</details>
