universal-json-agent-mcp 0.2.0

MCP server for advanced JSON parsing — load, query, aggregate, transform any JSON file from GitHub Copilot, Claude, Cursor, or any MCP client.

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

VS Code / GitHub Copilot

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.

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor

Add to your Cursor MCP settings:

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

CLI / Standalone

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

More test commands

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

MCP server not appearing in Copilot / Claude / Cursor

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

"No document loaded" errors

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

Truncated output

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

429 Too Many Requests (web server)

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

Import errors in web server

uv sync --extra web

---

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