5queezer/mcp-json

MCP JSON Server

A Model Context Protocol (MCP) server for JSON file operations, schema inference, and data transformation.

Overview

This MCP server provides comprehensive JSON manipulation tools and resources that can be used with Claude Desktop and other MCP-compatible clients. It offers powerful capabilities for reading, writing, transforming, and analyzing JSON data from files and URLs.

Features

🔧 Tools

Core JSON Tools:

• get_data - Fetch JSON data from files or URLs with optional JSON pointer access
• get_schema - Infer JSON schema from data sources
• schema_of - Generate JSON schema from text input
• write_json - Write JSON data to files with formatting options
• update_json - Update specific values using JSON pointers
• delete_json_key - Remove keys or array elements
• merge_json - Merge JSON data with multiple strategies (update/replace/deep)
• transform_json - Transform data (flatten/unflatten/keys_only/values_only)

🚀 Market Data Optimization Tools (Token Efficient):

• get_ohlcv_summary - Get OHLCV statistical summaries instead of raw data
• get_market_stats - Calculate field statistics (min/max/mean) for numeric data
• query_market_data - Filter and paginate large datasets efficiently
• get_top_performers - Get top N records by any metric
• get_data_sample - Get representative samples of large datasets

📁 Resources

• json://file/{path} - Direct access to JSON files
• json://url/{encoded_url} - Direct access to JSON from URLs

🎯 Key Capabilities

• JSON Pointer support (RFC 6901) for precise data access
• Schema inference with JSON Schema Draft 2020-12 compliance
• Multiple merge strategies for combining JSON data
• Data transformation utilities (flatten/unflatten nested objects)
• Support for both local files and HTTP/HTTPS URLs
• Comprehensive error handling and validation

Installation

Option 1: Install from PyPI (when published)

pip install mcp-json-server

Option 2: Install from Source

git clone <repository-url>
cd mcp-json-server
pip install -e .

Option 3: Development Installation

git clone <repository-url>
cd mcp-json-server
pip install -e ".[dev]"

Quick Start

1. Start the Server

# Using the console script
mcp-json-server

# Or run directly
python src/mcp_json_server.py

2. Configure Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "mcp-json-server": {
      "command": "mcp-json-server"
    }
  }
}

3. Basic Usage Examples

Read JSON Data

# Read entire file
get_data(source="data.json")

# Read with JSON pointer
get_data(source="config.json", pointer="/database/host")

# Read from URL  
get_data(source="https://api.example.com/data.json")

Generate Schemas

# Infer schema from file
get_schema(source="users.json", title="User Schema")

# Generate schema from JSON text
schema_of(json_text='{"name": "Alice", "age": 30}')

Update Data

# Update a specific value
update_json("config.json", "/database/port", 5432)

# Add new data
update_json("settings.json", "/features/new_feature", true)

Transform Data

# Flatten nested objects
transform_json("nested.json", "flat.json", "flatten")

# Extract just the keys structure
transform_json("data.json", "keys.json", "keys_only")

JSON Pointer Usage

This server supports JSON Pointer (RFC 6901) for precise data access:

{
  "users": [
    {"name": "Alice", "profile": {"city": "NYC"}},
    {"name": "Bob", "profile": {"city": "LA"}}
  ],
  "meta": {"total": 2}
}

Pointer Examples:

• "" or "/" → entire document
• "/users" → users array
• "/users/0" → first user
• "/users/0/name" → "Alice"
• "/users/1/profile/city" → "LA"
• "/meta/total" → 2

Alternative Formats:

• "/users/0/name" (standard)
• "#/users/0/name" (with hash prefix)
• "users/0/name" (without leading slash)

Tool Reference

Data Access Tools

get_data(source, pointer="")

Fetch JSON data with optional JSON pointer filtering.

• source: File path or URL
• pointer: JSON pointer for data selection (optional)

get_schema(source, pointer="", title="Schema")

Generate JSON schema from data source.

• source: File path or URL
• pointer: JSON pointer to specific data (optional)
• title: Schema title

schema_of(json_text, title="Schema")

Generate JSON schema from JSON text input.

• json_text: JSON string to analyze
• title: Schema title

Data Modification Tools

write_json(file_path, data, indent=2)

Write JSON data to file with formatting.

• file_path: Output file path
• data: JSON data to write
• indent: Indentation spaces

update_json(file_path, json_pointer, new_value)

Update specific value using JSON pointer.

• file_path: Target JSON file
• json_pointer: Path to value
• new_value: New value to set

delete_json_key(file_path, json_pointer)

Delete key or array element.

• file_path: Target JSON file
• json_pointer: Path to delete

merge_json(target_file, source_data, strategy="update")

Merge JSON data with different strategies.

• target_file: File to merge into
• source_data: Data to merge
• strategy: "update", "replace", or "deep"

Data Transformation Tools

transform_json(source_path, output_path, transformation)

Transform JSON data structure.

• source_path: Input file
• output_path: Output file
• transformation: "flatten", "unflatten", "keys_only", "values_only"

Resources

File Resource: json://file/{path}

Direct access to local JSON files.

Example:

json://file/config.json
json://file/data/users.json

URL Resource: json://url/{encoded_url}

Direct access to JSON from HTTP/HTTPS URLs.

Example:

json://url/https%3A//api.example.com/data.json

Note: URLs must be percent-encoded

Development

Running Tests

# Run all tests
python test_runner.py

# Run unit tests only  
python -m pytest tests/

# Run specific test file
python tests/test_mcp_json.py

Project Structure

mcp-json-server/
├── src/
│   └── mcp_json_server.py    # Main server implementation
├── tests/
│   └── test_mcp_json.py      # Unit tests
├── test_runner.py            # Comprehensive test runner
├── usage_example.py          # Usage examples
├── pyproject.toml           # Project configuration
└── README.md               # This file

Dependencies

• mcp>=1.0.0 - Model Context Protocol framework
• requests>=2.28.0 - HTTP client for URL fetching

Development Dependencies:

• pytest>=7.0.0 - Testing framework
• pytest-asyncio>=0.21.0 - Async test support
• black>=22.0.0 - Code formatting
• ruff>=0.1.0 - Linting and code quality

Common Use Cases

Configuration Management

# Read current config
config = get_data(source="app-config.json")

# Update database port
update_json("app-config.json", "/database/port", 5433)

# Add feature flag
update_json("app-config.json", "/features/new_api", true)

API Data Processing

# Fetch from API
api_data = get_data(source="https://api.service.com/users")

# Save locally
write_json("users-backup.json", api_data)

# Transform for analysis
transform_json("users-backup.json", "users-flat.json", "flatten")

Schema Generation & Validation

# Generate schema from sample data
schema = get_schema(source="sample-data.json", title="Data Schema")

# Save schema
write_json("data-schema.json", schema)

# Generate schema for specific subset
user_schema = get_schema(source="users.json", pointer="/users/0", title="User")

Error Handling

The server provides detailed error messages for common issues:

• Invalid JSON syntax
• File not found errors
• Network connectivity issues
• Invalid JSON pointer paths
• Type mismatch errors

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests: python test_runner.py
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: Report bugs and request features via GitHub issues
• Documentation: See usage_example.py for more examples
• Testing: Run python test_runner.py to verify functionality