JsonLens 1.1.0

JsonLens

An MCP (Model Context Protocol) server that gives LLMs six tools for exploring arbitrarily large JSON files without loading them entirely into context.

Built with C# / .NET 10, stdio transport, and streaming JSON parsing via Utf8JsonReader.

Tools

Prerequisites

• .NET 10 SDK

Install

dotnet tool install -g JsonLens

Usage with Claude Code

Allow access to a specific directory:

claude mcp add json-lens -s user -- json-lens --allowed-paths "/path/to/json/files"

Allow access to the current working directory:

# Linux / macOS
claude mcp add json-lens -s user -- json-lens --allowed-paths "$(pwd)"

# Windows (PowerShell)
claude mcp add json-lens -s user -- json-lens --allowed-paths "$PWD"

# Windows (cmd)
claude mcp add json-lens -s user -- json-lens --allowed-paths "%cd%"

To scope it to the current project only (instead of all projects):

claude mcp add json-lens -s project -- json-lens --allowed-paths "$(pwd)"

Allow multiple directories (semicolon-separated):

claude mcp add json-lens -s user -- json-lens --allowed-paths "/data/exports;/home/user/json"

Other Integrations

VS Code

Add to .vscode/mcp.json:

{
  "servers": {
    "json-lens": {
      "type": "stdio",
      "command": "json-lens",
      "args": ["--allowed-paths", "/path/to/json/files"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "json-lens": {
      "command": "json-lens",
      "args": ["--allowed-paths", "/path/to/json/files"]
    }
  }
}

Configuration

The server requires at least one allowed directory. Pass via --allowed-paths (semicolon-separated) or the JSON_LENS_ALLOWED_PATHS environment variable.

Filter Expression Syntax

The json_search tool accepts a filter expression language:

# Comparisons
age > 18
price <= 100.50
status == "active"

# String operations
name contains "john"
email matches "^[a-z]+@example\\.com$"

# Logical operators
age >= 18 AND age < 65
status == "active" OR status == "pending"
NOT deleted == true

# Grouping
(age > 20 AND age < 40) OR name == "Bob"

# Nested fields
address.city == "Seattle"

# Array quantifiers (v1.1.0+)
items[any].price > 100           # At least one item matches
items[all].inStock == true       # Every item matches
orders[any].items[all].valid     # Chained quantifiers

# Array length (v1.1.0+)
orders.length > 10               # Filter by array size
items.length == 0                # Empty arrays

# Array index access (v1.1.0+)
items[0].name == "first"         # First element
items[-1].status == "done"       # Last element
history[-2].action == "save"     # Second-to-last

# Field existence (v1.1.0+)
exists(discount)                 # Field is present (including null)
NOT exists(deletedAt)            # Field is absent
exists(customer.phoneNumber)     # Nested path existence

Array Quantifier Semantics

Development

Build from source

dotnet build src/JsonLens/JsonLens.csproj
dotnet run --project src/JsonLens/JsonLens.csproj -- --allowed-paths "/path/to/json/files"

Run tests

dotnet test tests/JsonLens.Tests/JsonLens.Tests.csproj

Project structure

src/JsonLens/
  Program.cs              # MCP server bootstrap (stdio)
  Models/                 # QueryResult, SchemaNode, FilterExpression, SummaryStatistics
  Services/               # FileAccessGuard, JsonStreamReader, PathNavigator, SchemaAnalyzer, FilterEngine
  Tools/                  # Six MCP tool classes

tests/JsonLens.Tests/
  Services/               # Unit tests for all services
  Tools/                  # Integration tests for all tools
  Fixtures/               # Sample JSON files

Security

• File access is restricted to a configurable directory allowlist
• Paths are canonicalized to prevent traversal attacks
• Access denied errors do not reveal file existence
• Server refuses to start without at least one allowed path

License

MIT