JSON Explorer MCP Server

An MCP (Model Context Protocol) server for efficiently exploring large JSON files without loading entire contents into context. Designed to help AI assistants navigate complex JSON data structures while minimizing token usage.

Features

- Lazy exploration - Only loads and returns what you need
- Smart truncation - Large values are automatically summarized
- Caching - Parsed JSON is cached with file modification checks
- Schema inference - Understand structure without reading all data
- Schema validation - Validate data against JSON Schema with $ref resolution
- Network schemas - Validate against remote schemas from SchemaStore
- Aggregate statistics - Get counts, distributions, and numeric stats for arrays
- Templates - Create JSON files from built-in or custom templates

Installation

``bash
npm install -g json-explorer-mcp
`

Or use directly with npx:

`bash
npx json-explorer-mcp
`

Usage

$3

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

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

$3

Add to .mcp.json in your project:

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

Tools

$3

| Tool | Description |
|------|-------------|
| json_inspect | Get file overview: size, structure type, depth-limited preview |
| json_keys | List keys/indices at a path with types and previews |
| json_get | Get value at path (auto-truncates large values) |
| json_search | Search for keys or values matching a pattern (regex) |
| json_sample | Sample items from arrays (first, last, random, range) |
| json_stats | Aggregate statistics for arrays |

$3

| Tool | Description |
|------|-------------|
| json_schema | Infer JSON schema from data at a path |
| json_validate | Validate against JSON Schema (file, URL, or inline) |
| is_json | Check if a file contains valid JSON |

$3

| Tool | Description |
|------|-------------|
| json_set | Set value at path with optional schema validation |
| json_format | Reformat with configurable indent and key sorting |

$3

| Tool | Description |
|------|-------------|
| list_templates | List available templates with metadata and schema URLs |
| get_template | Get full template details including all examples |
| create_json | Create file from template example |
| create_template | Create a new user template definition |
| add_template_example | Add example to existing user template |

Prompts

Prompts are reusable workflow templates that guide the AI through common tasks.

| Prompt | Description |
|--------|-------------|
| explore-json | Get started exploring a JSON file with overview and suggestions |
| validate-config | Validate a config file (tsconfig, package.json, etc.) against SchemaStore |
| create-config | Create a new configuration file from a template with guidance |

Built-in Templates

Templates include metadata, usage instructions, multiple examples, and schema URLs for validation.

| Template | Schema | Examples |
|----------|--------|----------|
| tsconfig | tsconfig.json | minimal, strict, library |
| package | package.json | minimal, typescript, library |
| eslint | eslintrc.json | basic, typescript |
| prettier | prettierrc.json | default, minimal |
| mcp-config | - | basic, multiple |
| vscode-launch | - | node, node-attach, jest |
| vscode-tasks | - | npm |
| vscode-settings | - | typescript |

$3

`typescript
// List available templates
list_templates()

// Get full template details
get_template(template: "tsconfig")

// Create a file from a template example
create_json(
template: "tsconfig",
example: "strict",
outputFile: "tsconfig.json"
)

// Create with overrides
create_json(
template: "package",
example: "typescript",
outputFile: "package.json",
overrides: { name: "my-project", version: "1.0.0" }
)
`

Environment Variables

| Variable | Description |
|----------|-------------|
| JSON_EXPLORER_TEMPLATES | Directory path for user template definitions |
| JSON_EXPLORER_NO_NETWORK | Set to 1 to disable all network requests |
| JSON_EXPLORER_NETWORK_TIMEOUT | Network request timeout in seconds (default: 30) |

User Templates

Create custom templates by setting JSON_EXPLORER_TEMPLATES to a directory path:

`json
{
"mcpServers": {
"json-explorer": {
"command": "npx",
"args": ["-y", "json-explorer-mcp"],
"env": {
"JSON_EXPLORER_TEMPLATES": "/path/to/templates"
}
}
}
}
`

$3

Create a JSON file in your templates directory (e.g., my-config.json):

`json
{
"description": "My application configuration",
"usage": "Place in project root to configure the app",
"filePatterns": ["myconfig.json", ".myconfig"],
"schemaUrl": "https://example.com/schema.json",
"examples": [
{
"name": "basic",
"description": "Minimal configuration",
"content": {
"setting": "value"
}
},
{
"name": "advanced",
"description": "Full configuration with all options",
"content": {
"setting": "value",
"debug": true,
"options": {}
}
}
]
}
`

The filename (without .json) becomes the template name.

$3

`typescript
// Create a new template
create_template(
name: "my-config",
description: "My application configuration",
usage: "Place in project root",
filePatterns: ["myconfig.json"],
schemaUrl: "https://example.com/schema.json",
exampleName: "basic",
exampleDescription: "Minimal configuration",
exampleContent: { setting: "value" }
)

// Add another example to an existing template
add_template_example(
templateName: "my-config",
exampleName: "production",
exampleDescription: "Production configuration",
exampleContent: { setting: "value", debug: false }
)
`

Network Schema Validation

Validate files against remote schemas from SchemaStore:

`typescript
json_validate(
file: "package.json",
schema: "https://json.schemastore.org/package.json",
resolveNetworkRefs: true,
strict: false
)
`

> Note: Very large schemas (like tsconfig) may timeout due to AJV compilation complexity.

Tool Details

$3

Get an overview of a JSON file including size, structure type, and a depth-limited preview.

`typescript
json_inspect(file: "/path/to/data.json")
`

Returns:

`json
{
"file": "/path/to/data.json",
"size": "13.1 MB",
"type": "object",
"preview": {
"users": "[... 1000 items]",
"config": "{... 5 keys}"
},
"topLevelInfo": "Object with 2 keys: users, config"
}
`

$3

List all keys (for objects) or indices (for arrays) at a given path with type info and previews.

`typescript
json_keys(file: "/path/to/data.json", path: "$.users")
`

$3

Retrieve the value at a specific path. Large values are automatically truncated.

`typescript
json_get(file: "/path/to/data.json", path: "$.users[0]")
`

$3

Set a value at a specific JSONPath with optional schema validation.

`typescript
// Simple set
json_set(
file: "/path/to/data.json",
path: "$.users[0].name",
value: "New Name"
)

// With schema validation
json_set(
file: "/path/to/data.json",
path: "$.users[0]",
value: { id: 1, name: "Alice" },
schema: "/path/to/user-schema.json"
)

// With inferred schema (validates type matches existing)
json_set(
file: "/path/to/data.json",
path: "$.config.maxRetries",
value: 5,
inferSchema: true
)

// Dry run (validate without writing)
json_set(
file: "/path/to/data.json",
path: "$.config.enabled",
value: true,
dryRun: true
)
`

$3

Reformat a JSON file with configurable indentation and optional key sorting.

`typescript
json_format(
file: "/path/to/data.json",
indent: 2,
sortKeys: true,
outputFile: "/path/to/formatted.json"
)
`

$3

Validate JSON data against a JSON Schema with support for $ref resolution.

`typescript
// With inline schema
json_validate(
file: "/path/to/data.json",
schema: { type: "object", required: ["id"] },
path: "$.users[0]"
)

// With schema file (local $refs resolved automatically)
json_validate(
file: "/path/to/data.json",
schema: "/path/to/schema.json"
)

// With network schema
json_validate(
file: "/path/to/data.json",
schema: "https://json.schemastore.org/package.json",
resolveNetworkRefs: true,
strict: false
)

// With schema directory (loads all schemas by $id)
json_validate(
file: "/path/to/data.json",
schemaDir: "/path/to/schemas/",
schemaId: "main-schema"
)
`

$3

Get aggregate statistics for array fields.

`typescript
json_stats(file: "/path/to/data.json", path: "$.users")
`

Returns field-level statistics including counts, distributions, and numeric stats.

JSONPath Syntax

All path parameters support JSONPath syntax:

- $ - Root object
- $.foo - Property access
- $.foo.bar - Nested property
- $.users[0] - Array index
- $.$id - Special keys with $ prefix
- $["special-key"] - Bracket notation for special characters

Security

$3

By default, network resolution is disabled. Enable per-request with resolveNetworkRefs: true.

To completely disable network requests (overrides all options):

`json
{
"mcpServers": {
"json-explorer": {
"command": "npx",
"args": ["-y", "json-explorer-mcp"],
"env": {
"JSON_EXPLORER_NO_NETWORK": "1"
}
}
}
}
`

$3

All referenced schemas are validated to ensure they're actual JSON Schema objects before use.

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Run in development mode

npm run dev
``

License

MIT