This server is a powerful Model Context Protocol (MCP) tool that processes, filters, and generates schemas from JSON data sourced from local files or remote URLs.
Core capabilities:
Generate TypeScript interfaces from JSON data using json_schema for type safety
Smart filtering with json_filter to extract specific fields based on defined shapes, supporting nested objects and arrays
Pre-filtering analysis using json_dry_run to analyze data size and get chunking recommendations before processing
Handle large datasets with automatic 400KB chunking and chunkIndex parameter for manageable data retrieval
Multi-source support for local files, HTTP/HTTPS URLs, and API endpoints
Built-in protection with 50MB size limits and comprehensive error handling to prevent memory issues
LLM optimization by filtering large JSON responses to reduce noise and improve performance in AI contexts
Provides specific configuration instructions for integrating with Claude Desktop on macOS systems through the macOS configuration file.
Leverages quicktype to convert JSON samples into TypeScript type definitions, enabling type safety and improved code structure when working with JSON data.
Generates TypeScript type definitions from JSON files, providing type safety and better code structure when working with JSON data in TypeScript environments.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@JSON Filter MCP filter this API response to only show user names and emails"
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.
A powerful Model Context Protocol (MCP) server that provides JSON schema generation and filtering tools for local files and remote HTTP/HTTPS endpoints. Built with quicktype for robust TypeScript type generation.
Perfect for: Filtering large JSON files and API responses to extract only relevant data for LLM context, while maintaining type safety.
🔄 Schema Generation - Convert JSON to TypeScript interfaces using quicktype
🎯 Smart Filtering - Extract specific fields with shape-based filtering
🌐 Remote Support - Works with HTTP/HTTPS URLs and API endpoints
📦 Auto Chunking - Handles large datasets with automatic 400KB chunking
🛡️ Size Protection - Built-in 50MB limit with memory safety
⚡ MCP Ready - Seamless integration with Claude Desktop and Claude Code
🚨 Smart Errors - Clear, actionable error messages with debugging info
Related MCP server: JSON Query MCP
json_schemaGenerates TypeScript interfaces from JSON data.
Parameters:
filePath: Local file path or HTTP/HTTPS URL
Example:
// Input JSON
{"name": "John", "age": 30, "city": "New York"}
// Generated TypeScript
export interface GeneratedType {
name: string;
age: number;
city: string;
}json_filterExtracts specific fields using shape-based filtering with automatic chunking for large datasets.
Parameters:
filePath: Local file path or HTTP/HTTPS URL
shape: Object defining which fields to extract
chunkIndex (optional): Chunk index for large datasets (0-based)
Auto-Chunking:
≤400KB: Returns all data
400KB: Auto-chunks with metadata
json_dry_runAnalyzes data size and provides chunking recommendations before filtering.
Parameters:
filePath: Local file path or HTTP/HTTPS URL
shape: Object defining what to analyze
Returns: Size breakdown and chunk recommendations
// Simple field extraction
json_filter({
filePath: "https://api.example.com/users",
shape: {"name": true, "email": true}
})// Single field
{"name": true}
// Nested objects
{"user": {"name": true, "email": true}}
// Arrays (applies to each item)
{"users": {"name": true, "age": true}}
// Complex nested
{
"results": {
"profile": {"name": true, "location": {"city": true}}
}
}// 1. Check size first
json_dry_run({filePath: "./large.json", shape: {"users": {"id": true}}})
// → "Recommended chunks: 6"
// 2. Get chunks
json_filter({filePath: "./large.json", shape: {"users": {"id": true}}})
// → Chunk 0 + metadata
json_filter({filePath: "./large.json", shape: {"users": {"id": true}}, chunkIndex: 1})
// → Chunk 1 + metadataRemote Data Fetching: This tool fetches data from HTTP/HTTPS URLs. Users are responsible for:
✅ Safe Practices:
Verify URLs point to legitimate endpoints
Use trusted, public APIs only
Respect API rate limits and terms of service
Review data sources before processing
❌ Maintainers Not Responsible For:
External URL content
Privacy implications of remote requests
Third-party API abuse or violations
💡 Recommendation: Only use trusted, public data sources.
# No installation required
npx json-mcp-filter@latestnpm install -g json-mcp-filter@latest
json-mcp-servergit clone <repository-url>
cd json-mcp-filter
npm install
npm run buildAdd to your configuration file:
{
"mcpServers": {
"json-mcp-filter": {
"command": "npx",
"args": ["-y", "json-mcp-filter@latest"]
}
}
}# Add via CLI
claude mcp add json-mcp-filter npx -y json-mcp-filter@latestOr add manually:
Name: json-mcp-filter
Command: npx
Args: ["-y", "json-mcp-filter@latest"]
npm run build # Compile TypeScript
npm run start # Run compiled server
npm run inspect # Debug with MCP inspector
npx tsc --noEmit # Type check onlynpm run inspect # Interactive testing interfacesrc/
├── index.ts # Main server + tools
├── strategies/ # Data ingestion strategies
│ ├── JsonIngestionStrategy.ts # Abstract interface
│ ├── LocalFileStrategy.ts # Local file access
│ └── HttpJsonStrategy.ts # HTTP/HTTPS fetching
├── context/
│ └── JsonIngestionContext.ts # Strategy management
└── types/
└── JsonIngestion.ts # Type definitionsLocal Files: Not found, permissions, invalid JSON
Remote URLs: Network failures, auth errors (401/403), server errors (500+)
Content Size: Auto-reject >50MB with clear messages
Format Detection: Smart detection of HTML/XML with guidance
Rate Limiting: 429 responses with retry instructions
Processing: Quicktype errors, shape filtering issues
All errors include actionable debugging information.
File Size | Processing Time |
< 100 KB | < 10ms |
1-10 MB | 100ms - 1s |
10-50 MB | 1s - 5s |
> 50 MB | Blocked |
50MB maximum for all sources
Pre-download checking via Content-Length
Memory safety prevents OOM errors
Clear error messages with actual vs. limit sizes
Use json_dry_run first for large files
Filter with json_filter before schema generation
Focus shapes on essential fields only
Public APIs - REST endpoints with JSON responses
Static Files - JSON files on web servers
Local Dev - http://localhost during development
Local Files - File system access
LLM Integration:
API returns large response
json_filter extracts relevant fields
Process clean data without noise
json_schema generates types for safety
A hosted deployment is available on Fronteir AI.
Analyze the size breakdown of JSON data using a shape object to determine granularity. Returns size information in bytes for each specified field, mirroring the shape structure but with size values instead of data.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the JSON file (local) or HTTP/HTTPS URL to analyze | |
| shape | No | Shape object (formatted as valid JSON) defining what to analyze for size. Use 'true' to get total size of a field, or nested objects for detailed breakdown. Examples: 1. Get size of single field: {"name": true} 2. Get sizes of multiple fields: {"name": true, "email": true, "age": true} 3. Get detailed breakdown: {"user": {"name": true, "profile": {"bio": true}}} 4. Analyze arrays: {"posts": {"title": true, "content": true}} - gets total size of all matching elements 5. Complex analysis: { "metadata": true, "users": { "name": true, "settings": { "theme": true } }, "posts": { "title": true, "tags": true } } Note: - Returns size in bytes for each specified field - Output structure mirrors the shape but with size values - Array analysis returns total size of all matching elements - Use json_schema tool to understand the JSON structure first |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key behaviors: it returns size information in bytes, mirrors the shape structure in output, and handles arrays by returning total size of all matching elements. However, it lacks details on error handling, performance implications, or rate limits, which could be relevant for a tool processing potentially large JSON files.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded with the core purpose, followed by detailed parameter explanations. It uses bullet points and examples efficiently, but could be slightly more concise by integrating the 'Note' section into the main text or reducing redundancy in examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (analyzing JSON size with shape objects) and lack of output schema, the description does a good job of explaining what the tool returns. It covers input semantics and behavioral traits adequately. However, without annotations or output schema, it could benefit from more detail on error cases or output format specifics to be fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 100%, so the baseline is 3. The description adds significant value by explaining the 'shape' parameter with detailed examples and notes on how it affects output (e.g., using 'true' for total size, nested objects for breakdowns, and array handling). This clarifies semantics beyond the schema's technical definition, though it doesn't add much for 'filePath' beyond what the schema already states.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Analyze the size breakdown of JSON data using a shape object to determine granularity.' It specifies the verb ('analyze'), resource ('JSON data'), and method ('using a shape object'), distinguishing it from sibling tools like json_filter and json_schema by focusing on size analysis rather than filtering or schema extraction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on when to use this tool: 'Use json_schema tool to understand the JSON structure first.' This indicates a prerequisite step, helping the agent sequence operations correctly and avoid misuse by analyzing data without prior structural understanding.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Filter JSON data using a shape object to extract only the fields you want. Provide filePath (local file or HTTP/HTTPS URL) and shape parameters.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | Path to the JSON file (local) or HTTP/HTTPS URL to filter | |
| shape | No | Shape object (formatted as valid JSON) defining what fields to extract. Use 'true' to include a field, or nested objects for deep extraction. Examples: 1. Extract single field: {"type": true} 2. Extract multiple fields: {"type": true, "version": true, "source": true} 3. Extract nested fields: {"appState": {"gridSize": true, "viewBackgroundColor": true}} 4. Extract from arrays: {"elements": {"type": true, "x": true, "y": true}} - applies to each array item 5. Complex nested extraction: { "type": true, "version": true, "appState": { "gridSize": true, "viewBackgroundColor": true }, "elements": { "type": true, "text": true, "x": true, "y": true, "boundElements": { "type": true, "id": true } } } Note: - Arrays are automatically handled - the shape is applied to each item in the array. - Use json_schema tool to analyse the JSON file schema before using this tool. - Use json_dry_run tool to get a size breakdown of your desired json shape before using this tool. | |
| chunkIndex | No | Index of chunk to retrieve (0-based). If filtered data exceeds 400KB, it will be automatically chunked. Defaults to 0 if not specified. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and adds valuable behavioral context: it explains automatic chunking when data exceeds 400KB, describes how arrays are handled ('applied to each item'), and mentions the need for valid JSON formatting. It doesn't cover error handling or performance limits, but provides substantial operational guidance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded with the core purpose. The examples section is extensive but necessary for understanding the shape parameter. The workflow guidance about sibling tools is efficiently placed at the end. Some minor redundancy exists between the initial description and shape parameter examples.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 3 parameters, no annotations, and no output schema, the description provides substantial context: clear purpose, sibling tool relationships, behavioral details (chunking, array handling), and extensive parameter examples. The main gap is lack of information about return format or error conditions, but overall coverage is strong given the complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline would be 3. The description adds meaningful context beyond schema: it provides concrete examples of shape parameter usage (5 detailed examples), explains the 'true' value convention, and clarifies array handling. However, it doesn't add semantic context for filePath or chunkIndex beyond what's in their schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('filter JSON data'), resource ('JSON data'), and mechanism ('using a shape object to extract only the fields you want'). It distinguishes from siblings by mentioning them as preparatory tools (json_schema, json_dry_run) rather than alternatives for the same filtering purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is provided on when to use this tool vs alternatives: 'Use json_schema tool to analyse the JSON file schema before using this tool' and 'Use json_dry_run tool to get a size breakdown of your desired json shape before using this tool.' This clearly establishes a recommended workflow with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Generate TypeScript schema for a JSON file or remote JSON URL. Provide the file path or HTTP/HTTPS URL as the only parameter.
| Name | Required | Description | Default |
|---|---|---|---|
| filePath | Yes | JSON file path (local) or HTTP/HTTPS URL to generate schema from |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions generating a schema but lacks details on error handling, output format, performance considerations, or any constraints like rate limits or authentication needs, leaving significant gaps for a tool that processes external resources.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded and concise, consisting of two clear sentences that directly state the tool's function and parameter requirement without any redundant or unnecessary information, making it highly efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity in handling external JSON sources and no output schema or annotations, the description is incomplete. It fails to address critical aspects like the format of the generated TypeScript schema, error responses for invalid inputs, or limitations, which are essential for effective use by an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds minimal semantics beyond the input schema, which already has 100% coverage. It reiterates that the parameter is a 'file path or HTTP/HTTPS URL' but does not provide additional context like supported file formats, URL protocols beyond HTTP/HTTPS, or examples, so it meets the baseline for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Generate') and resource ('TypeScript schema for a JSON file or remote JSON URL'), distinguishing it from sibling tools like json_dry_run and json_filter by focusing on schema generation rather than validation or filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the input type ('JSON file or remote JSON URL'), but does not explicitly state when to use this tool versus alternatives like json_dry_run or json_filter, nor does it provide exclusions or prerequisites for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
json_dry_runjson_filterjson_schemaScored across 3 tools
Each tool has a distinct and non-overlapping purpose: json_dry_run analyzes size breakdowns, json_filter extracts specific fields, and json_schema generates TypeScript schemas. The descriptions clearly differentiate their functions, with no ambiguity in tool selection.
All tool names follow a consistent 'json_' prefix pattern with descriptive suffixes (dry_run, filter, schema). This uniform naming convention makes the tool set predictable and easy to understand, enhancing usability.
With 3 tools, this server is well-scoped for JSON filtering and analysis tasks. Each tool serves a clear and essential function in the domain, avoiding bloat while covering core operations like filtering, schema generation, and size analysis.
The tool set covers key JSON operations: filtering, schema generation, and size analysis, which are fundamental for JSON processing. A minor gap exists in lacking direct manipulation tools (e.g., json_merge or json_transform), but the provided tools enable effective agent workflows without dead ends.
Query your Google Sheets as structured JSON: list sheets and tabs, read schemas, filter rows.
Compare two JSON files deeply, regardless of order. Get a detailed difference report highlighting…
Query Inbin's parsed email events (newsletters, invoices, alerts) as typed JSON tools.
Compare two JSON files deeply, ignoring order, to surface every difference. Get a clear, structure…
