MCP JSON Tools

What is MCP JSON Tools?

MCP JSON Tools is an MCP server that lets you interact with local JSON and NDJSON (JSONL) files by querying with JSONPath and manipulating data via Lodash. It provides four tools—mcp_json_query, mcp_json_nodes, mcp_json_eval, and mcp_json_multi_eval—for developers using MCP‑compatible clients like Cursor or VS Code.

How to use MCP JSON Tools?

Configure your client to run the server via npx (recommended) or Node directly. In your client’s mcp.json (e.g., for Cursor or VS Code), set "command": "npx" and "args": ["mcp-json-tools"]. When using npx, all file paths passed to the tools must be absolute paths. Tools accept parameters such as file_path, json_path, js_code, and optionally count.

Key features of MCP JSON Tools

• Unified format handling: reads both JSON and NDJSON automatically
• Query data using standard JSONPath expressions (mcp_json_query)
• Inspect values and their precise paths (mcp_json_nodes)
• Analyze or modify files with sandboxed JavaScript (Lodash + JSONPath) (mcp_json_eval, mcp_json_multi_eval)
• Modifications preserve the original file format (JSON or NDJSON)
• Safe execution via Node.js vm module with configurable timeouts

Use cases of MCP JSON Tools

• Querying specific fields from a JSON file using JSONPath
• Inspecting the structure of a JSON or NDJSON file by retrieving values and paths
• Performing complex analysis (e.g., calculating averages) with custom JavaScript
• Modifying JSON/NDJSON files in place (e.g., adding properties or filtering records)
• Batch processing multiple JSON/NDJSON files simultaneously

FAQ from MCP JSON Tools

What file formats are supported?

JSON and newline-delimited JSON (NDJSON/JSONL). NDJSON files are automatically treated as an array of objects.

How can I modify a file?

Use mcp_json_eval (single file) or mcp_json_multi_eval (multiple files). The last expression in your JavaScript code must be { type: 'updateFile', data: <new_data> } (or { type: 'updateMultipleFiles', updates: [...] }).

What JavaScript libraries are available in the eval tools?

Lodash (as _) and jsonpath (as jp) are pre‑loaded in the sandboxed VM. The file content is available as $1 (object for JSON, array for NDJSON).

What is the timeout for eval tools?

Both mcp_json_eval and mcp_json_multi_eval have a 30‑second timeout.

Is the sandboxed execution fully secure?

No. The code runs inside Node.js’s vm module, which is safer than raw eval() but still poses risks of resource exhaustion or unintended logic. Only execute trusted code.