How do I use Universal JSON Agent MCP?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Universal JSON Agent MCP Load the file sales.json and calculate total revenue" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Universal JSON Agent MCP

Talk to your JSON files using natural language.

26 powerful tools to load, explore, query, aggregate, transform, and export — right from your AI editor.

uv tool install universal-json-agent-mcp

Getting Started · 26 Tools · Web Server · Development

Why?

Working with JSON shouldn't require writing a script every time. This tool lets you ask questions in plain English and get answers instantly.

You:  What's the total budget across all missions?

AI:   The total budget across all missions is $18,250,000,000.50
      (Used tools: load_json → sum_values)

Supported Clients

			Any MCP Client
VS Code / Copilot	Claude Desktop	Cursor	stdio

⚡ Getting Started

1. Install

uv tool install universal-json-agent-mcp   # install CLI once
uvx universal-json-agent-mcp               # run without installing
uv add universal-json-agent-mcp            # add dependency to your project

2. Configure your editor

Create .vscode/mcp.json in your workspace:

{
  "servers": {
    "universal-json-agent": {
      "type": "stdio",
      "command": "universal-json-agent-mcp"
    }
  }
}

Tip: Prefer zero-install? Use "command": "uvx" with "args": ["universal-json-agent-mcp"] instead.

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "universal-json-agent": {
      "command": "universal-json-agent-mcp"
    }
  }
}

Add to your Cursor MCP settings:

{
  "mcpServers": {
    "universal-json-agent": {
      "command": "universal-json-agent-mcp"
    }
  }
}

universal-json-agent-mcp
# or
uv run python -m universal_json_agent_mcp

Starts on stdio — pipe any MCP client into it.

3. Start asking questions

> Load data/orders.json and tell me what's inside
> How many missions have status "in_progress"?
> What's the total budget across all missions?
> Filter personnel where role contains "engineer"
> Sort by priority descending and show codenames
> Export the filtered results to CSV

🛠 Tools Reference

Load & Manage

Tool	What it does
`load_json`	Load a JSON file from disk into memory
`list_loaded`	List all loaded documents with metadata
`unload_json`	Remove a document from memory

Explore

Tool	What it does
`get_keys`	Get keys of an object or index range of an array
`get_value`	Retrieve value at a path (auto-truncated at 10 KB)
`get_type`	Return the JSON type at a path
`get_structure`	Schema-like skeleton — keys, types, nesting

Query

Tool	What it does
`jsonpath_query`	Run JSONPath — `$.missions[*].codename`
`filter_objects`	Filter by condition: `eq`, `gt`, `lt`, `contains`, `regex`…
`search_text`	Full-text search across all string values

Aggregate

Tool	What it does
`count`	Count items in an array or keys in an object
`sum_values`	Sum numeric values at a JSONPath
`min_max`	Get min and max of numeric values
`unique_values`	Distinct values at a JSONPath
`value_counts`	Frequency table — like pandas `value_counts()`

Transform

Tool	What it does
`flatten`	Flatten nested objects to dot-notation pairs
`pick_fields`	Project specific fields from array objects
`group_by`	Group objects by a field value
`sort_by`	Sort objects by a field
`sample`	Random N items from an array

Analytics

Tool	What it does
`describe`	Stats: count, mean, std, min, max, percentiles
`multi_filter`	Compound filters with AND / OR logic
`compare`	Diff two values — added, removed, changed keys

Export

Tool	What it does
`export_csv`	Export array of objects to CSV file
`export_json`	Export a value to a new JSON file

Introspect

Tool	What it does
`distinct_paths`	List every unique leaf path with types

🌐 Web Server Subproject (web/)

Optional FastAPI + LangChain web-server subproject inside this repo, wrapping all 26 root MCP tools for integrations, dashboards, or non-MCP workflows.

uv sync --extra web                       # install web deps with uv
cp .env.example .env                     # add your OpenRouter key
uv run python -m web.run --port 8000     # start server with uv
# open docs in browser: http://127.0.0.1:8000/docs

Endpoints

Method	Endpoint	Description
`GET`	`/health`	Health check
`POST`	`/query`	Upload JSON + ask a question
`POST`	`/query/path`	Reference a file on disk + ask a question
`GET`	`/docs`	Interactive Swagger UI

Example

curl -X POST http://localhost:8000/query \
  -F "file=@data/missions.json" \
  -F "query=What's the total budget?"

{
  "answer": "The total budget across all missions is $18,250,000,000.50",
  "tools_used": ["load_json", "sum_values"]
}

Configuration

Variable	Required	Default	Description
`OPENROUTER_API_KEY`	✅	—	Your OpenRouter API key
`OPENROUTER_MODEL`	—	`openai/gpt-4o-mini`	Any supported model

🧑‍💻 Development

git clone https://github.com/GautamVhavle/universal-json-agent.git
cd universal-json-agent
uv sync --extra dev
uv run pytest                            # 489 tests

uv run pytest -v                                        # verbose
uv run pytest tests/test_tools/test_aggregate.py        # one file
uv run pytest -k "test_filter"                          # by pattern

Releasing

Releases are fully automated via GitHub Actions:

git tag v0.3.0 -m "v0.3.0"
git push origin v0.3.0

Then create a GitHub Release for the tag — CI runs tests, builds, and publishes to PyPI.

Troubleshooting

Verify the config file exists (.vscode/mcp.json for VS Code)
Check the command is on your PATH: which universal-json-agent-mcp
Restart the editor

You need to load a file first. Ask your AI: "Load the file data/example.json" — this calls load_json behind the scenes.

Large results are capped at ~10 KB. Use more specific paths, filters, or pick_fields to narrow results.

The model provider is rate-limiting you. Wait a moment or switch to a different model in your .env file.

uv sync --extra web

MIT License · Built with ❤️ by Gautam Vhavle · Star this repo if it helped you ⭐

Universal JSON Agent MCP

Universal JSON Agent MCP

Talk to your JSON files using natural language.

Why?

Supported Clients

⚡ Getting Started

1. Install

2. Configure your editor

3. Start asking questions

🛠 Tools Reference

Load & Manage

Explore

Query

Aggregate

Transform

Analytics

Export

Introspect

🌐 Web Server Subproject (web/)

Endpoints

Example

Configuration

🧑‍💻 Development

Releasing

Troubleshooting

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API