JS
Developer Tools

JSON MCP Server: JSONPath Arrays, Strings, Numbers, Dates

Query and process JSON with an MCP server using JSONPath for arrays, strings, numbers, and date operations.

View on GitHub
Quick Install
npx -y @GongRzhe/JSON-MCP-Server

Overview

This MCP (Model Context Protocol) server provides a lightweight, HTTP-accessible set of JSON processing tools driven by JSONPath and common operations for arrays, strings, numbers, and dates. It is intended to be used as a tool endpoint for language models or other agents that need reliable, programmatic access to manipulate and query JSON data without embedding heavy processing logic in prompts.

The server exposes discrete “tools” that accept JSON inputs and return structured JSON outputs. Each tool focuses on a single kind of operation (for example, array filtering with JSONPath, string extraction with regex, numeric aggregation, or date parsing/formatting). That makes it easy to call from an MCP-capable client and chain results in multi-step reasoning or data-pipeline scenarios.

Features

  • JSONPath-based array querying and selection
  • String processing: regex extract, replace, split, join, trim
  • Numeric operations: sum, average, min, max, count, map/transform
  • Date handling: parse multiple formats, format to ISO, compute diffs
  • Light-weight HTTP interface compatible with MCP tooling patterns
  • Deterministic JSON outputs suitable for downstream programmatic use
  • Small footprint and easy to self-host from source

Installation / Configuration

Clone the repository, install dependencies, and run the server locally. The project uses Node.js and npm (or yarn).

Clone and install:

git clone https://github.com/GongRzhe/JSON-MCP-Server.git
cd JSON-MCP-Server
npm install

Run the server (default port 8080):

# development
npm start

# or directly with node if provided entrypoint
node ./src/index.js

Environment variables:

# example
export MCP_PORT=8080
export NODE_ENV=production

If the repository includes an npm script for building:

npm run build
npm run start:prod

Note: Adjust commands to match package.json scripts in the repository. See the project README and package.json for exact script names.

Available Tools

The server exposes a set of named tools. The example table below summarizes commonly provided tool names, their purpose, and the key arguments they accept.

Tool namePurposeKey arguments
jsonpath.querySelect nodes from JSON using JSONPathdata (JSON), path (string)
array.filterFilter array by JSONPath predicate or expressiondata (array), predicate (JSONPath or expression)
string.matchExtract substring(s) via regexdata (string), pattern (regex), group (int optional)
string.replaceReplace strings using regex or literaldata (string), pattern, replacement
number.aggregateAggregate numeric arrays (sum, avg, min, max)data (array of numbers), op (sum
date.parseParse date strings into ISO timestampsdata (string), format (optional)
date.formatFormat ISO date to a given patterndata (ISO string), format
date.diffCompute difference between two datesfrom, to, unit (days

Tool invocations typically accept a JSON body describing the tool and its arguments and return a structured JSON result.

Use Cases

  1. Filter an array of products where price > 100 Request:
{
  "tool": "jsonpath.query",
  "args": {
    "data": { "products": [ { "name": "A", "price": 120 }, { "name": "B", "price": 80 } ] },
    "path": "$.products[?(@.price > 100)]"
  }
}

Response:

{ "result": [ { "name": "A", "price": 120 } ] }
  1. Extract first capture group from a log message Request:
{
  "tool": "string.match",
  "args": {
    "data": "user=alice id=42",
    "pattern": "user=(\\w+)",
    "group": 1
  }
}

Response:

{ "result": "alice" }
  1. Sum numeric values in an array Request:
{
  "tool": "number.aggregate",
  "args": {
    "data": [10, 20, 30],
    "op": "sum"
  }
}

Response:

{ "result": 60 }
  1. Parse a date string and compute days between two dates Request:
{
  "tool": "date.diff",
  "args": {
    "from": "2023-01-01",
    "to": "2023-01-15",
    "unit": "days"
  }
}

Response:

{ "result": 14 }

Example HTTP call (generic)

Below is a generic curl example showing the kind of request you send to invoke a tool. Adjust the URL and JSON shape to the server’s actual API.

curl -X POST http://localhost:8080/mcp/tool \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "jsonpath.query",
    "args": {
      "data": { "users": [ {"name":"x","age":30} ] },
      "path": "$.users[?(@.age>=30)]"
    }
  }'

Resources

  • Source and issues: https://github.com/GongRzhe/JSON-MCP-Server
  • Inspect package.json and README in the repository for exact scripts and any additional configuration options.
  • Use MCP-compatible clients or simple HTTP POST requests to integrate this server into an LLM toolchain or automation pipeline.

Notes for Developers

  • The server is intended to be deterministic and return machine-friendly JSON; design calling code to handle structured results and errors.
  • When composing multi-step MCP workflows, prefer small, single-purpose tool invocations (for example, query then aggregate) to keep output predictable.
  • Validate input sizes when sending large JSON payloads to avoid performance issues; the server is optimized for typical JSON sizes used in tool-based workflows.
Tags:developer-tools