MCP JSON Lens

Look at big JSON without loading big JSON.

MCP JSON Lens is an MCP server and CLI that summarize and query JSON and JSONL files with a small jq-like expression language. Ask for the shape of a document, or pull exactly the values you need — the rest never reaches your context. Use it as an MCP tool so agents can explore datasets safely, or straight from the terminal.

Sixth tool in the TokenSaver family: TokenSaver MCP maps repositories, MCP Context Budget audits tool costs, MCP Web Snapshot reads the web, MCP Log Tail summarizes logs, MCP Secret Scan guards commits, and JSON Lens explores data.

Product requirements: PRD.md · PRD.id.md (Bahasa Indonesia)

Why

The fastest way to destroy a context window is pasting a large JSON file into it. But agents constantly need to answer small questions about big data: what shape is this export, which records failed, what are the ids. JSON Lens answers those questions with compact, bounded output instead of the whole document.

Related MCP server: Fetch JSONPath MCP

Quick start

Inspect structure — no expression needed:

npx -y mcp-json-lens inspect ./data.json

# JSON inspection: ./data.json
Kind: json | 198 B
Type: object (3 keys)
- users: array[3] of object
    items:
    - id: number (sample 1)
    - name: string (sample "Ada")
    - roles: array[2]
- total: number (sample 3)
- page: number (sample 1)

Query values with a jq-like expression:

npx -y mcp-json-lens query ./data.json --expr '.users[*].name'

# Query: .users[*].name
Kind: json | matches: 3 | showing: 3

[
  "Ada",
  "Budi",
  "Citra"
]

Works the same on JSONL, with line numbers:

npx -y mcp-json-lens query ./events.jsonl --expr '.level, .user' --limit 2

[
  { "line": 1, "value": { ".level": "info", ".user": "ada" } },
  { "line": 2, "value": { ".level": "error", ".user": "budi" } }
]

Expression cheatsheet

Pipes: keys, length, type. Multiple paths and pipes cannot be combined in v0.1.0.

MCP server

Add it to any MCP-compatible client:

{
  "mcpServers": {
    "jsonlens": {
      "command": "npx",
      "args": ["-y", "mcp-json-lens", "serve"]
    }
  }
}

From a local checkout, point command at node and args at the built entry point:

{
  "mcpServers": {
    "jsonlens": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-json-lens/dist/index.js", "serve"]
    }
  }
}

Tools

Design principles

• Bounded: file size caps, line caps, result limits, and token budgets everywhere.

• Offline: no network, no telemetry; data never leaves your machine.

• Read-only: never writes to your files.

• Format-tolerant: JSON and JSONL, including mislabeled files.

• Honest: truncation and omitted keys are always reported.

CLI reference

mcp-json-lens inspect <file> [--json]
mcp-json-lens query <file> --expr <expression> [--limit <n>] [--json]
mcp-json-lens serve

Exit codes: 0 success, 1 file or expression failure, 2 usage error.

Roadmap

• More pipes: sort, unique, map(.field), select(.field == value).

• Bracket-quoted keys (.["weird key"]) and slices (.[1:5]).

• Streaming JSONL queries with early exit for very large files.

• NDJSON output mode for piping between tools.

• CSV and Parquet inspection.

Development

npm install
npm run typecheck
npm run build
npm test

The suite covers the expression parser and evaluator, schema summarization, JSON and JSONL loading, query execution, rendering, CLI behavior, and MCP round trips.

License

MIT — see LICENSE.