MCP JSON Navigator
A Model Context Protocol (MCP) server that provides intelligent JSON navigation and search capabilities for AI assistants. Mostly design for saving tokens and manipulating large files > 10MB in a few seconds.
Require FileSystem. Note the json should note use "." in keys
Capabilities
- "Search keys & values ("phone", "email", "location")"
- "Precise path lookup with optional case-sensitive matching"
- "Structural exploration of very large JSON files (without loading everything into model context)"
📦 Installation
MacOS/Linux
git clone https://github.com/Adsdworld/mcp-json-navigator && cd mcp-json-navigator && npm install && npm run build
Windows (tested)
git clone https://github.com/Adsdworld/mcp-json-navigator; cd mcp-json-navigator; npm install; npm run build
⚙️ Configuration
Add to your MCP settings file (e.g., claude_desktop_config.json):
{
"mcpServers": {
"json-navigator": {
"command": "node",
"args": ["C:\\Users\\YOUR_USERNAME\\mcp-json-navigator\\build\\index.js"]
}
}
}
Replace YOUR_USERNAME and the path with your actual installation location.
🔎 Json-query
{
"Request": {
"limit": 50,
"query": "phone",
"filepath": "C:\\Shared\\With\\Claude\\data.json",
"caseSensitive": false
},
"Response": {
"results": [
{
"path": "result[0]",
"score": 2
},
{
"path": "result[1]",
"score": 2
}
]
}
}
🛤️ Json-explore
{
"Request": {
"filepath": "C:\\Shared\\With\\Claude\\data.json",
"jsonpath": "result[1]",
"verbosity": 5
},
"Response": {
"message": "Hello, Brannon! Your order number is: #100",
"phoneNumber": "(268) 822-7569",
"phoneVariation": "+90 343 871 10 66",
"status": "disabled",
"name": "{object: 3 keys, 49 chars}",
"username": "Madalyn-Koss",
"password": "_jRAnwKTcLZwdj6",
"emails": "[list: 2 items, 54 chars]",
"location": "{object: 6 keys, 175 chars}",
"website": "https://sour-debris.com/",
"domain": "wrong-leaf.org",
"job": "{object: 5 keys, 123 chars}",
"creditCard": "{object: 3 keys, 60 chars}",
"uuid": "476c7b47-0c28-4dc1-b872-7c4256a95675",
"objectId": "68fe628328b168737793b750"
}
}
🎯 Who is this for?
This tool is designed for AI assistants that need to navigate and search through large JSON files efficiently.
When dealing with massive JSON structures (hundreds of MB, deeply nested objects, thousands of entries), AI models face several challenges:
- Token limitations: Large JSON files can't fit entirely in the context window
- Performance: Parsing and searching large structures is slow
- Precision: Finding specific data in complex nested structures is difficult
MCP JSON Navigator solves these problems by:
- Providing intelligent exploration with adjustable verbosity levels
- Using fuzzy search with camelCase tokenization for natural queries
- Allowing precise navigation using JSON paths
- Grouping and scoring results intelligently
✨ Features
1. Smart JSON Exploration (json-explore)
Navigate through JSON structures with adjustable detail levels:
// Get an overview (verbosity: 0-1)
{ "users": "list", "config": "object", "version": "string" }
// See structure with counts (verbosity: 2-3)
{ "users": "[list: 150 items]", "config": "{object: 12 keys, 450 chars}" }
// Full expansion for small objects (verbosity: 4-5)
{ "users": [...], "config": {...} }
Parameters:
filepath: Path to the JSON filejsonpath(optional): Navigate to specific path (e.g.,users[0].profile)verbosity: 0-5 (default: 4)0: Keys only1: Keys with types2: Keys with counts3: Keys with counts and character sizes4: Smart expansion for small objects5: Raw data
listDisplayLimit: Max items to show in arrays (default: 5)objectDisplayLimit: Max keys to show in objects (default: 6)charDisplayLimit: Max characters for expansion (default: 200)
2. Intelligent Search (json-query)
Search through keys and values with fuzzy matching and camelCase tokenization:
// These all find "phoneNumber" and "phoneVariation"
query: "phone" ✓
query: "number" ✓
query: "variation" ✓
How it works:
- Tokenization: Splits camelCase, snake_case, kebab-case, and generates n-grams
- Fuzzy Matching: Uses similarity scoring to find partial matches
- Weighted Scoring: Keys score higher than values
- Smart Grouping: Groups related results from the same JSON branch
Parameters:
filepath: Path to the JSON filequery: Search term (supports partial matches)limit: Max results to return (default: 20, min: 10)caseSensitive: Enable exact matching filter (default: false)
When caseSensitive: true, returns an additional exactMatch field with results that contain the exact query string.
🚀 Usage Examples
Example 1: Exploring a Large JSON File
// First, get an overview
json-explore({
filepath: "C:\\Shared\\With\\Claude\\data.json",
verbosity: 1
})
// → { "users": "list", "products": "list", "config": "object" }
// Then navigate to a specific section
json-explore({
filepath: "C:\\Shared\\With\\Claude\\data.json",
jsonpath: "users[0]",
verbosity: 5
})
// → Full details of the first user
Example 2: Searching for Contacts
// Find all phone-related fields by high scores paths
json-query({
filepath: "C:\\Shared\\With\\Claude\\contacts.json",
query: "phone",
limit: 20
})
// → Results with paths like "contacts[0].phoneNumber", "contacts[1].phoneVariation"
// Returning a list of exact paths found that exactly match + high scores paths
json-query({
filepath: "C:\\Shared\\With\\Claude\\contacts.json",
query: "qsbHBJ5sd4HBSDsdjhHBS",
caseSensitive: true
})
Example 3: Complex Navigation
// Navigate deep into nested structures
json-explore({
filepath: "api-response.json",
jsonpath: "result.data.items[3].metadata",
verbosity: 3
})
// → Full details metadata either an object / list / primitif
🛠️ Technical Details
Architecture
- TypeScript-based: Fully typed for reliability
- MCP Protocol: Built on Model Context Protocol standard
- Fast Fuzzy Search: Uses
fast-fuzzylibrary for efficient matching - Inverted Index: Builds searchable index with n-gram tokenization
- Smart Grouping: Groups results by JSON structure for better relevance
Search Algorithm
-
Tokenization:
- Normalizes text (camelCase → camel Case)
- Generates 3-5 character n-grams
- Builds inverted index: token → [paths with weights]
-
Query Phase:
- Tokenizes query
- Computes fuzzy similarity scores
- Accumulates scores per path
- Applies key/value weights
-
Result Grouping:
- Groups paths by structural similarity
- Scores by frequency × depth
- Returns top representative paths
📄 License
MIT License - See LICENSE file for details.
You are free to:
- ✓ Use commercially
- ✓ Modify
- ✓ Distribute
- ✓ Use privately
Just mention the source: https://github.com/Adsdworld/mcp-json-navigator
🤝 Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
📚 Related Projects
🔗 Links
- GitHub: https://github.com/Adsdworld/mcp-json-navigator
- MCP Documentation: https://modelcontextprotocol.io/
Built with ❤️ for AI assistants navigating complex JSON structures.