MCP JSON Reader (mcp-json-reader)

A Model Context Protocol (MCP) server for reading, querying, and filtering local JSON files using extended JSONPath syntax. It allows LLMs to perform complex sorting, aggregations, math, and string operations directly on local datasets.

Quick Start

Run the server directly via npx:

npx mcp-json-reader --root /path/to/your/json/data

Related MCP server: JSON Query MCP

Tools Exposed

Example Queries

• Sort & Slice: $.items.sort(-price)[0:5] (Sort items by price descending and return top 5)

• Aggregation: $.transactions.sum(amount) (Sum transaction amounts)

• Complex Filter: $.users with condition @.email.endsWith('@gmail.com')

Command Line Options & Env Variables

• Command Line: --root <base_path> (Optional)

• Environment Variable: MCP_JSON_ROOT (Optional)

If neither is provided, the server defaults to the Current Working Directory (CWD) of the process.

Configuration Snippets

Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-json-reader": {
      "command": "npx",
      "args": ["-y", "mcp-json-reader", "--root", "/absolute/path/to/your/json/data"]
    }
  }
}

Cursor

Go to Settings > Features > MCP, click Add New MCP Server:

• Name: mcp-json-reader

• Type: command

• Command: npx -y mcp-json-reader --root /absolute/path/to/your/json/data

Cline / Roo-Code

Add this to your cline_mcp_settings.json (or roo_mcp_settings.json):

{
  "mcpServers": {
    "mcp-json-reader": {
      "command": "npx",
      "args": ["-y", "mcp-json-reader", "--root", "/absolute/path/to/your/json/data"]
    }
  }
}

Windsurf

Add this to your mcp_config.json:

{
  "mcpServers": {
    "mcp-json-reader": {
      "command": "npx",
      "args": ["-y", "mcp-json-reader", "--root", "/absolute/path/to/your/json/data"]
    }
  }
}

GitHub Copilot (Coding Agent / CLI)

For the Copilot agent configuration:

{
  "mcpServers": {
    "mcp-json-reader": {
      "command": "npx",
      "args": ["-y", "mcp-json-reader", "--root", "/absolute/path/to/your/json/data"],
      "tools": ["*"]
    }
  }
}

The query tool supports standard JSONPath plus the following custom extensions:

• Sorting: .sort(field) (ascending) or .sort(-field) (descending)

• Aggregation: .sum(field), .avg(field), .min(field), .max(field)

• Numeric Ops: .math(+10), .math(*2), .round(), .abs(), .sqrt(), etc.

• String Ops: .contains('x'), .startsWith('x'), .toLowerCase(), .toUpperCase(), etc.

• Date Ops: .format('YYYY-MM-DD'), .isToday()

• Array Ops: .distinct(), .reverse(), [start:end] (slice)

Caching

The server implements an in-memory LRU cache (up to 10 entries) for parsed JSON objects. Subsequent queries on the same file skip the read and parse steps. The cache automatically detects file modifications using file timestamps and invalidates stale entries.

V8 Heap Memory Limits

Node.js imposes a default heap memory limit of ~4 GB on 64-bit systems. Parsing JSON constructs in-memory object graphs that consume 2–6× the raw file size.

To tune limits for larger files:

# Increase V8 heap (e.g., to 8 GB)
node --max-old-space-size=8192 ./build/index.js

# Increase the file size limit via environment variable (in MB)
MCP_MAX_FILE_SIZE_MB=2048 npx mcp-json-reader

Server Identity

• Name: mcp-json-reader

• Primary command: npx -y mcp-json-reader

• Input Schema & Tools:

  1. query (reads and queries JSONPath)

     • path (string): Absolute or relative file path.

     • jsonPath (string): Extended JSONPath expression.

  2. filter (filters array datasets)

     • path (string): Absolute or relative file path.

     • jsonPath (string): JSONPath pointing to an array.

     • condition (string): Condition expression (e.g., @.price > 10).

AI Instructions for Installation

If the user asks you (the AI model) to install or configure this MCP server:

1. Locate their IDE's MCP configuration file (e.g., claude_desktop_config.json for Claude Desktop, cline_mcp_settings.json for Cline, or mcp_config.json for Windsurf).

2. Add mcp-json-reader under the mcpServers object using:

   • Command: "npx"

   • Args: ["-y", "mcp-json-reader", "--root", "<project_root_or_data_directory>"]

3. Ensure the --root argument matches the workspace or data directory they intend to query.

Development

npm install
npm run build
npm test