Query JSON values with JSONPath expressions via @mukundakatta/jsonpath-mcp (npx)
JSONPath is the JSON equivalent of XPath for XML — a query language for extracting values from nested JSON structures. This MCP server wraps jsonpath-plus and exposes a single query tool. Accepts any JSON value and a JSONPath expression, returns matched values. Essential for agents processing API responses, config files, or any structured JSON data.
Recipe: JSONPath queries on JSON documents via @mukundakatta/jsonpath-mcp
Setup
npx -y @mukundakatta/jsonpath-mcpTransport: NDJSON (MCP SDK v1.29.0 — newline-delimited JSON, NOT Content-Length headers). Server version: jsonpath v0.1.0.
Tool inventory
One tool: query — accepts {"json": <any JSON value>, "path": "<JSONPath expression>", "result_type": "value"|"path"|"all"}.
Backed by jsonpath-plus. Supports: $ root, . child, .. recursive descent, [*] wildcard, [?()] filter expressions.
Verified trace
MCP handshake:
→ {"jsonrpc":"2.0","id":1,"method":"initialize",...}
← {"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{}},"serverInfo":{"name":"jsonpath","version":"0.1.0"}},"jsonrpc":"2.0","id":1}Query 1 — wildcard selector (all book titles):
→ tools/call query {"json": {"store":{"book":[...]}}, "path": "$.store.book[*].title"}
← {"matches": ["The Lord of the Rings", "Dune", "The C Programming Language"]}Query 2 — filter expression (books under $25):
→ tools/call query {"json": ..., "path": "$.store.book[?(@.price < 25)]"}
← {"matches": [{"category":"fiction","author":"Tolkien","title":"The Lord of the Rings","price":22.99}, {"category":"fiction","author":"Herbert","title":"Dune","price":8.95}]}Query 3 — recursive descent (all prices in the document):
→ tools/call query {"json": ..., "path": "$..price"}
← {"matches": [22.99, 8.95, 39.95, 399]}Gotchas
- Parameters are
json(any JSON value) andpath(JSONPath string) — NOTjson_data. - The
jsonparameter accepts the raw JSON object, not a stringified version. - Uses NDJSON framing (SDK v1.29.0), NOT Content-Length headers. Sending Content-Length frames produces zero output.
- Results are wrapped in
{"matches": [...]}— always an array, even for single-value matches. - Optional
result_type:"value"(default, returns matched values),"path"(returns JSONPath locations),"all"(returns both).
{ "init": { "request": { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": { "name": "pathfinder", "version": "1.0" } } }, "response": { "result": { "protocolVersion": "2024-11-05", "capabilities": { "tools": {} }, "serverInfo": { "name": "jsonpath", "version": "0.1.0" } }, "jsonrpc": "2.0", "id": 1 } }, "tools_list": { "response": { "result": { "tools": [ { "name": "query", "description": "Apply a JSONPath expression to a JSON value. result_type: value (default), path, or all.", "inputSchema": { "type": "object", "properties": { "json": { "description": "Any JSON value." }, "path": { "type": "string", "description": "JSONPath, e.g. $.items[*].price" }, "result_type": { "type": "string", "enum": ["value", "path", "all"], "default": "value" } }, "required": ["json", "path"] } } ] }, "jsonrpc": "2.0", "id": 2 } }, "query_wildcard": { "request": { "jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": { "name": "query", "arguments": { "json": { "store": { "book": [ { "category": "fiction", "author": "Tolkien", "title": "The Lord of the Rings", "price": 22.99 }, { "category": "fiction", "author": "Herbert", "title": "Dune", "price": 8.95 }, { "category": "reference", "author": "Kernighan", "title": "The C Programming Language", "price": 39.95 } ], "bicycle": { "color": "red", "price": 399 } } }, "path": "$.store.book[*].title" } } }, "response": { "result": { "content": [ { "type": "text", "text": "{ "matches": [ "The Lord of the Rings", "Dune", "The C Programming Language" ] }" } ] }, "jsonrpc": "2.0", "id": 3 } }, "query_filter": { "request": { "jsonrpc": "2.0", "id": 4, "method": "tools/call", "params": { "name": "query", "arguments": { "json": { "store": { "book": [ { "category": "fiction", "author": "Tolkien", "title": "The Lord of the Rings", "price": 22.99 }, { "category": "fiction", "author": "Herbert", "title": "Dune", "price": 8.95 }, { "category": "reference", "author": "Kernighan", "title": "The C Programming Language", "price": 39.95 } ], "bicycle": { "color": "red", "price": 399 } } }, "path": "$.store.book[?(@.price < 25)]" } } }, "response": { "result": { "content": [ { "type": "text", "text": "{ "matches": [ { "category": "fiction", "author": "Tolkien", "title": "The Lord of the Rings", "price": 22.99 }, { "category": "fiction", "author": "Herbert", "title": "Dune", "price": 8.95 } ] }" } ] }, "jsonrpc": "2.0", "id": 4 } }, "query_recursive_descent": { "request": { "jsonrpc": "2.0", "id": 5, "method": "tools/call", "params": { "name": "query", "arguments": { "json": { "store": { "book": [ { "category": "fiction", "author": "Tolkien", "title": "The Lord of the Rings", "price": 22.99 }, { "category": "fiction", "author": "Herbert", "title": "Dune", "price": 8.95 }, { "category": "reference", "author": "Kernighan", "title": "The C Programming Language", "price": 39.95 } ], "bicycle": { "color": "red", "price": 399 } } }, "path": "$..price" } } }, "response": { "result": { "content": [ { "type": "text", "text": "{ "matches": [ 22.99, 8.95, 39.95, 399 ] }" } ] }, "jsonrpc": "2.0", "id": 5 } } }