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