MCP JSON Reader
oovz/mcp-json-reader
Consulte e filtre JSON locais com JSONPath estendido no seu LLM
Ver no GitHubServidor 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-reader1 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
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)
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
| Tool | Description | Key Arguments |
|---|---|---|
query | Queries local JSON using standard JSONPath + custom extensions (sorting, math, aggregates, etc.). | path (string), jsonPath (string) |
filter | Extracts 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:
$.userswith 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 Size | Estimated Heap Usage (parsed) | Fits in 4 GB V8 Heap? |
|---|---|---|
| 100 MB | 200–600 MB | Yes |
| 500 MB | 1–3 GB | Usually |
| 1 GB | 2–6 GB | Risky |
| 1.5 GB | 3–9 GB | At the edge |
| 2+ GB | 4–12 GB | No — 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:
query(reads and queries JSONPath)path(string): Absolute or relative file path.jsonPath(string): Extended JSONPath expression.
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:
- Locate their IDE's MCP configuration file (e.g.,
claude_desktop_config.jsonfor Claude Desktop,cline_mcp_settings.jsonfor Cline, ormcp_config.jsonfor Windsurf). - Add
mcp-json-readerunder themcpServersobject using:- Command:
"npx" - Args:
["-y", "mcp-json-reader", "--root", "<project_root_or_data_directory>"]
- Command:
- Ensure the
--rootargument matches the workspace or data directory they intend to query.
Development
npm install
npm run build
npm test