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

1. "Search keys & values ("phone", "email", "location")"
2. "Precise path lookup with optional case-sensitive matching"
3. "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 file
• jsonpath (optional): Navigate to specific path (e.g., users[0].profile)
• verbosity: 0-5 (default: 4)
  • 0: Keys only
  • 1: Keys with types
  • 2: Keys with counts
  • 3: Keys with counts and character sizes
  • 4: Smart expansion for small objects
  • 5: 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:

1. Tokenization: Splits camelCase, snake_case, kebab-case, and generates n-grams
2. Fuzzy Matching: Uses similarity scoring to find partial matches
3. Weighted Scoring: Keys score higher than values
4. Smart Grouping: Groups related results from the same JSON branch

Parameters:

• filepath: Path to the JSON file
• query: 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-fuzzy library for efficient matching
• Inverted Index: Builds searchable index with n-gram tokenization
• Smart Grouping: Groups results by JSON structure for better relevance

Search Algorithm

1. Tokenization:

   • Normalizes text (camelCase → camel Case)
   • Generates 3-5 character n-grams
   • Builds inverted index: token → [paths with weights]

2. Query Phase:

   • Tokenizes query
   • Computes fuzzy similarity scores
   • Accumulates scores per path
   • Applies key/value weights

3. 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

• Model Context Protocol
• MCP Servers

🔗 Links

• GitHub: https://github.com/Adsdworld/mcp-json-navigator
• MCP Documentation: https://modelcontextprotocol.io/

---

Built with ❤️ for AI assistants navigating complex JSON structures.