json-explorer-mcp

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

npm install -g json-explorer-mcp

Or use directly with npx:

npx json-explorer-mcp

Usage

With Claude Desktop

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

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

With Claude Code

Add to .mcp.json in your project:

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

Tools

Navigation

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

Schema & Validation

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

Editing

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

Templates

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

Using Templates

// 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:

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

Template File Format

Create a JSON file in your templates directory (e.g., my-config.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.

Creating Templates Programmatically

// 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:

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

json_inspect

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

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

Returns:

{
  "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"
}

json_keys

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

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

json_get

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

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

json_set

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

// 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
)

json_format

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

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

json_validate

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

// 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"
)

json_stats

Get aggregate statistics for array fields.

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

Network Schema Resolution

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

To completely disable network requests (overrides all options):

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

Schema Validation

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

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run in development mode
npm run dev

License

MIT