<div align="center">

<br />

<img src="https://raw.githubusercontent.com/GautamVhavle/universal-json-agent/main/assets/logo.png" alt="Universal JSON Agent MCP" width="180" />

<br />

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.

<br />

         

<br />

uv tool install universal-json-agent-mcp

<br />

Getting Started  ·  26 Tools  ·  Web Server  ·  Development

</div>

---

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

<div align="center">

<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vscode/vscode-original.svg" width="28" />	<img src="https://uxwing.com/wp-content/themes/uxwing/download/brands-and-social-media/claude-ai-icon.png" width="28" />	<img src="https://www.cursor.com/favicon.ico" width="28" />	Any MCP Client
VS Code / Copilot	Claude Desktop	Cursor	stdio

</div>

---

⚡ 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

<details open> <summary><b>VS Code / GitHub Copilot</b></summary>

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.

</details>

<details> <summary><b>Claude Desktop</b></summary>

Add to claude_desktop_config.json:

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

</details>

<details> <summary><b>Cursor</b></summary>

Add to your Cursor MCP settings:

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

</details>

<details> <summary><b>CLI / Standalone</b></summary>

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

Starts on stdio — pipe any MCP client into it.

</details>

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

<details> <summary><b>More test commands</b></summary>

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

</details>

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

<details> <summary><b>MCP server not appearing in Copilot / Claude / Cursor</b></summary>

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

</details>

<details> <summary><b>"No document loaded" errors</b></summary>

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

</details>

<details> <summary><b>Truncated output</b></summary>

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

</details>

<details> <summary><b>429 Too Many Requests (web server)</b></summary>

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

</details>

<details> <summary><b>Import errors in web server</b></summary>

uv sync --extra web

</details>

---

<div align="center">

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

</div>