convez.ai
MCP ServerDados & AnalyticsIntermediário
oovz

MCP JSON Reader

oovz/mcp-json-reader

Consulte e filtre JSON locais com JSONPath estendido no seu LLM

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que permite ler, consultar e filtrar arquivos JSON locais usando JSONPath estendido. Oferece operações avançadas como ordenação, agregações matemáticas e filtragem complexa diretamente em datasets locais, integrável em Claude Desktop, Cursor, VS Code e outras IDEs.

Instalação

$npx convez-ai oovz/mcp-json-reader

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 semana
Versão
v3.0.5
Issues abertas
1
Contribuidores
1

Casos de uso

  • Analisar e consultar estruturas de dados JSON com JSONPath avançado
  • Agregar e ordenar dados sem sair do contexto da IA
  • Filtrar arrays complexos com lógica customizada em tempo real

Veredito

Ferramenta sólida e bem integrada para LLMs acessarem dados JSON locais. Sintaxe JSONPath estendida oferece flexibilidade real; instalação direta via npx em múltiplas plataformas é um diferencial prático.

README

A tradução para o português deste README ainda está na fila.

MCP JSON Reader (mcp-json-reader)

npm version Install in VS Code Install in VS Code Insiders Install in Cursor

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

Tools Exposed

ToolDescriptionKey Arguments
queryQueries local JSON using standard JSONPath + custom extensions (sorting, math, aggregates, etc.).path (string), jsonPath (string)
filterExtracts and filters elements from an array in a local JSON file using advanced logic.path (string), jsonPath (string), condition (string)

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.

Raw File SizeEstimated Heap Usage (parsed)Fits in 4 GB V8 Heap?
100 MB200–600 MBYes
500 MB1–3 GBUsually
1 GB2–6 GBRisky
1.5 GB3–9 GBAt the edge
2+ GB4–12 GBNo — OOM crash

[!IMPORTANT] The default enforced file size limit is 1.5 GB per file.

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

[!NOTE] This section is optimized for AI assistants reading this README to understand how to auto-configure and use this server.

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
Ver o original no GitHub

Bom para

Relacionados