JSON MCP Server

An MCP server for common JSON data-processing tasks. It runs over stdio and exposes a focused set of tools for transforming JSON, removing nulls, converting CSV to JSON, generating TypeScript interfaces, and aggregating array data.

Features

• Runs as a standard stdio MCP server.
• Accepts JSON from inline strings, local files, or URLs.
• Supports both in-memory responses and optional file output for generated results.
• Ships with built-in MCP resources containing usage guides for every tool.
• Keeps the tool surface small and practical for automation workflows.

Available Tools

| Tool | Purpose | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | transform_keys | Recursively transform object keys using uppercase, lowercase, prefix, suffix, prefix+suffix, or exact-key replacement operations. | | remove_nulls | Recursively remove all null values from objects and arrays. | | json_to_ts | Generate TypeScript interfaces from JSON data. | | aggregate | Run sum, avg, min, max, and count over a JSON array or nested array. | | csv_to_json | Convert CSV or TSV data into a JSON array with automatic type inference. |

Built-in Resources

Each tool also exposes a guide resource that MCP clients can read for detailed examples:

• json-mcp://transform_keys_guide
• json-mcp://remove_nulls_guide
• json-mcp://json_to_ts_guide
• json-mcp://aggregate_guide
• json-mcp://csv_to_json_guide

Requirements

• Node.js 18 or newer
• npm

Node 18+ is recommended because the server uses modern ESM and the built-in fetch API for URL-based JSON input.

Installation

npm install

The package is also published on npm as json-utils-mcp-server

Build

npm run build

This compiles the TypeScript source into build/ and makes the entrypoint executable.

Run Locally

npm start

The server starts on stdio, which is the expected transport for MCP clients.

MCP Client Configuration

For local development from this repository, this project already includes a local MCP config in .mcp.json:

{
    "mcpServers": {
        "json-mcp-server": {
            "command": "node",
            "args": ["./build/index.js"],
            "env": {}
        }
    }
}

If you want to run the published package directly from npm, use npx in your MCP client config:

{
    "servers": {
        "json-mcp-server": {
            "command": "npx",
            "args": ["-y", "json-utils-mcp-server@latest"]
        }
    }
}

For clients that accept a manual stdio server definition, use the local node ./build/index.js command after building the project, or the published npx -y json-utils-mcp-server@latest command.

Input Conventions

JSON-based tools

The transform_keys, remove_nulls, json_to_ts, and aggregate tools accept JSON in one of these forms:

{ "type": "jsonString", "jsonString": "{\"name\":\"Alice\"}" }

{ "type": "jsonFilePath", "jsonFilePath": "/absolute/path/data.json" }

{ "type": "jsonUrl", "jsonUrl": "https://example.com/data.json" }

CSV tool

The csv_to_json tool accepts either inline CSV text or a file path:

{ "type": "csvString", "csvString": "name,age\nAlice,30" }

{ "type": "csvFilePath", "csvFilePath": "/absolute/path/data.csv" }

Tool Reference

transform_keys

Transforms object keys recursively. Transformations are applied in order, and only keys are changed.

Supported transformations:

• { "type": "upper" }
• { "type": "lower" }
• { "type": "prefix", "prefix": "api_" }
• { "type": "suffix", "suffix": "_v2" }
• { "type": "prefix_suffix", "prefix": "pre_", "suffix": "_post" }
• { "type": "replace", "oldKey": "fname", "newKey": "firstName" }

Example:

{
    "json": {
        "type": "jsonString",
        "jsonString": "{\"userId\":1,\"profile\":{\"name\":\"Alice\"}}"
    },
    "transformations": [
        { "type": "prefix", "prefix": "api_" },
        { "type": "upper" }
    ]
}

Optional outputFilePath writes the transformed JSON to disk instead of returning it directly.

remove_nulls

Removes null values recursively from objects and arrays while keeping other falsy values such as false, 0, and empty strings.

Example:

{
    "json": {
        "type": "jsonString",
        "jsonString": "{\"name\":\"Alice\",\"nickname\":null,\"tags\":[\"admin\",null],\"profile\":{\"active\":true,\"note\":null}}"
    }
}

Optional outputFilePath writes the cleaned JSON to disk.

json_to_ts

Generates TypeScript interface definitions using the shape of the provided JSON.

Example:

{
    "json": {
        "type": "jsonString",
        "jsonString": "{\"id\":1,\"name\":\"Alice\",\"profile\":{\"active\":true}}"
    }
}

Optional outputFilePath writes the generated definitions to a .ts file.

aggregate

Aggregates values from a root array or a nested array.

Rules:

• count does not require field.
• sum, avg, min, and max require field.
• field and arrayPath use dot notation.
• Non-numeric values at the resolved field cause an error.
• null and undefined numeric field values are ignored.

Example:

{
    "json": {
        "type": "jsonString",
        "jsonString": "[{\"price\":10},{\"price\":20},{\"price\":15}]"
    },
    "operations": ["count", "sum", "avg", "min", "max"],
    "field": "price"
}

Nested-array example:

{
    "json": {
        "type": "jsonFilePath",
        "jsonFilePath": "/absolute/path/data.json"
    },
    "operations": ["min", "max", "count"],
    "field": "stats.score",
    "arrayPath": "data.records"
}

csv_to_json

Converts CSV into a JSON array of objects using the first row as headers.

Parsing behavior:

• Empty cells become null.
• true and false become booleans.
• Numeric values become numbers.
• Quoted fields and escaped quotes are supported.
• Trailing empty lines are ignored.

Example:

{
    "csv": {
        "type": "csvString",
        "csvString": "name,age,active\nAlice,30,true\nBob,25,false"
    }
}

TSV example:

{
    "csv": {
        "type": "csvString",
        "csvString": "name\tcity\nAlice\tLondon\nBob\tBerlin"
    },
    "delimiter": "\t"
}

Optional outputFilePath writes the resulting JSON to disk.

Development

Useful scripts:

npm run build
npm run watch
npm run format

Project Structure

src/
  index.ts              MCP server bootstrap
  utils.ts              Shared JSON input parsing
  tools/
    aggregate/
    csvToJson/
    jsonToTs/
    removeNulls/
    transformKeys/
build/                  Compiled output

Notes

• All file path inputs are expected to be absolute paths.
• Tool responses are returned as text content, with JSON payloads pretty-printed where applicable.
• If outputFilePath is provided, the relevant tool writes the output file and returns a short confirmation message instead of the full payload.