JSON MCP Server
A high-performance MCP server for comprehensive JSON file operations, including reading, writing, and advanced querying, optimized for LLM interactions.
JSON MCP Server
A high-performance Rust-based Model Context Protocol (MCP) server that provides comprehensive JSON file operations optimized for LLM interactions. This server enables LLMs to efficiently read, write, query, and manipulate JSON files with support for extremely large datasets and advanced querying capabilities.
š Features
Core JSON Tools
- š json-read: Read JSON files with optional JSONPath filtering and pagination
- āļø json-write: Write or update JSON files with multiple merge strategies
- š json-query: Execute complex JSONPath queries with various output formats
- ā json-validate: Validate JSON structure and syntax with detailed diagnostics
- ā json-help: Interactive help system with comprehensive examples and troubleshooting
Key Capabilities
- Large File Support: Efficient pagination and streaming for files of any size
- JSONPath Querying: Full JSONPath support for complex data extraction and filtering
- Flexible Writing: Multiple modes (replace, merge_shallow, merge_deep, append) with backup options
- LLM-Optimized: Detailed error messages and usage examples for optimal LLM interaction
- Memory Efficient: Smart pagination prevents memory overflow on large datasets
- MCP Compliant: Full Model Context Protocol support with proper error handling
- Debug Logging: File-based debug logging for troubleshooting without violating MCP protocol
š¦ Installation
Quick Install
Via Cargo (Recommended)
cargo install json-mcp-server
Via Installation Script
# Linux/macOS
curl -fsSL https://raw.githubusercontent.com/ciresnave/json-mcp-server/main/scripts/install.sh | bash
# Windows PowerShell
iwr https://raw.githubusercontent.com/ciresnave/json-mcp-server/main/scripts/install.ps1 | iex
Pre-built Binaries
Download platform-specific binaries from GitHub Releases:
- Windows:
json-mcp-server-v{version}-x86_64-pc-windows-msvc.zip
- macOS:
json-mcp-server-v{version}-x86_64-apple-darwin.tar.gz
- Linux:
json-mcp-server-v{version}-x86_64-unknown-linux-gnu.tar.gz
Package Managers
Debian/Ubuntu (.deb packages)
# Download and install .deb package
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/json-mcp-server_*_amd64.deb
sudo dpkg -i json-mcp-server_*_amd64.deb
RHEL/Fedora/CentOS (.rpm packages)
# Download and install .rpm package
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/json-mcp-server-*.x86_64.rpm
sudo rpm -i json-mcp-server-*.x86_64.rpm
Arch Linux (AUR)
# Manual install using PKGBUILD
wget https://github.com/ciresnave/json-mcp-server/releases/latest/download/PKGBUILD
makepkg -si
Building from Source
# Clone the repository
git clone https://github.com/ciresnave/json-mcp-server.git
cd json-mcp-server
# Build the project
cargo build --release
# Run the server
cargo run
Verification
After installation, verify it works:
json-mcp-server --version
json-mcp-server --help
Usage
The JSON MCP Server communicates via JSON-RPC over stdin/stdout following the Model Context Protocol specification.
Getting Started
-
Start the server:
cargo run
-
Get help: Use the
json-help
tool to learn about available functionality:{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "json-help", "arguments": {"topic": "overview"} } }
Example Usage
Reading JSON Files
{
"name": "json-read",
"arguments": {
"file_path": "./data.json",
"json_path": "$.users[*].name",
"format": "pretty"
}
}
Writing JSON Data
{
"name": "json-write",
"arguments": {
"file_path": "./config.json",
"data": {"setting": "value", "enabled": true},
"mode": "merge"
}
}
Querying with JSONPath
{
"name": "json-query",
"arguments": {
"file_path": "./products.json",
"query": "$.products[?(@.price > 100)].name",
"format": "table"
}
}
Processing Large Files
{
"name": "json-read",
"arguments": {
"file_path": "./large-dataset.json",
"json_path": "$.records[*].id",
"limit": 1000,
"offset": 0
}
}
Tool Reference
json-read
Read and parse JSON files with optional JSONPath filtering and pagination.
Parameters:
file_path
(string, required): Path to JSON filejson_path
(string, optional): JSONPath expression for filteringstart_index
(integer, optional): Starting index for pagination (default: 0)limit
(integer, optional): Maximum items to return (default: 1000)output_format
(string, optional): Output format - "json", "pretty", "compact" (default: "json")
json-write
Write or update JSON files with flexible merge strategies.
Parameters:
file_path
(string, required): Path to JSON filecontent
(string, required): JSON content to writemode
(string, optional): Write mode - "replace", "merge_shallow", "merge_deep", "append" (default: "replace")
json-query
Execute JSONPath queries on JSON files with various output formats.
Parameters:
file_path
(string, required): Path to JSON filejson_path
(string, required): JSONPath query expressionoutput_format
(string, optional): Output format - "json", "pretty", "compact", "csv", "markdown" (default: "json")
json-validate
Validate JSON file structure and syntax.
Parameters:
file_path
(string, required): Path to JSON file to validate
json-help
Get comprehensive help about available tools and JSONPath syntax.
Parameters:
topic
(string, optional): Help topic - "overview", "tools", "jsonpath", "examples", "troubleshooting" (default: "overview")
JSONPath Support
The server supports full JSONPath syntax for querying JSON data:
$
- Root element.field
- Child field access[index]
- Array index access[*]
- All array elements..field
- Recursive descent[?(@.field > value)]
- Filter expressions{field1, field2}
- Projection
JSONPath Examples
# Get all user names
$.users[*].name
# Filter users over 25
$.users[?(@.age > 25)]
# Get nested data
$.data.items[*].details.price
# All prices anywhere in document
$..price
# Complex filtering
$.products[?(@.category == 'electronics' && @.price < 500)].name
Performance Notes
Large File Handling
- Files of any size: The
json-read
tool automatically uses streaming for memory efficiency - Line-delimited JSON: Automatically detected and processed efficiently
- Memory usage: Streaming keeps memory usage constant regardless of file size
Best Practices
- Use specific JSONPath queries to filter data early
- Set reasonable limits when processing large datasets
- Use offset for pagination through large result sets
- The server automatically optimizes for file size and available memory
Error Handling
The server provides detailed error messages to help diagnose issues:
- File not found: Clear path resolution guidance
- JSON syntax errors: Line and column information when available
- JSONPath errors: Syntax validation and suggestions
- Memory issues: Guidance on using streaming alternatives
MCP Client Configuration
The JSON MCP Server works with any MCP-compatible client. Detailed configuration guides are available in the examples/mcp_clients/
directory:
Supported Clients
- VS Code with GitHub Copilot - Complete setup guide
- Claude Desktop - Configuration and usage examples
- Generic MCP Client - Universal configuration guide
- Custom Implementation - Build your own client
Quick Setup
VS Code + GitHub Copilot:
{
"mcp.servers": {
"json-mcp-server": {
"path": "json-mcp-server"
}
}
}
Claude Desktop:
{
"mcpServers": {
"json-mcp-server": {
"command": "json-mcp-server",
"args": []
}
}
}
For detailed setup instructions, troubleshooting, and advanced configurations, see the respective client guides in the examples/mcp_clients/
directory.
Development
Project Structure
json-mcp-server/
āāā src/ # Source code
ā āāā main.rs # Application entry point and MCP server
ā āāā lib.rs # Library exports for testing
ā āāā mcp/ # MCP protocol implementation
ā ā āāā mod.rs
ā ā āāā protocol.rs # Protocol definitions and types
ā ā āāā server.rs # MCP server implementation
ā āāā json_tools/ # JSON tool implementations
ā āāā mod.rs
ā āāā handler.rs # Tool coordination and help system
ā āāā operations.rs # Read/write/validate operations
ā āāā query.rs # JSONPath querying with multiple formats
ā āāā streaming.rs # Large file streaming and pagination
āāā tests/ # Integration tests
ā āāā integration_tests.rs
āāā examples/ # Example configurations and data
ā āāā mcp_clients/ # Client configuration guides
ā ā āāā vscode.md # VS Code setup
ā ā āāā claude-desktop.md
ā ā āāā github-copilot.md
ā ā āāā generic.md # Generic MCP client setup
ā ā āāā client_implementation.md
ā ā āāā python_client.py
ā āāā sample-data.json # Sample test data
ā āāā test-commands.jsonl
ā āāā test-output.json
āāā dev_tools/ # Development and testing utilities
ā āāā README.md # Development tools documentation
ā āāā testing/ # Test scripts and utilities
ā āāā test_all_tools.py
ā āāā test_multiple_instances.py
ā āāā test_json_help.py
ā āāā [other test files]
āāā Cargo.toml # Rust project configuration
āāā README.md # This file
Building
# Development build
cargo build
# Release build
cargo build --release
# Run tests
cargo test
# Check for issues
cargo check
Dependencies
tokio
: Async runtimeserde
/serde_json
: JSON serializationjsonpath-rust
: JSONPath query supportanyhow
: Error handlingclap
: Command line parsing
License
This project is licensed under the MIT OR Apache-2.0 license.
Contributing
Contributions are welcome! Please ensure:
- Code follows Rust conventions
- All tests pass
- New features include appropriate tests
- Documentation is updated for new functionality
Support
For issues, questions, or contributions, please refer to the project repository.
Related Servers
Filesystem MCP Server
A secure server for filesystem operations with controlled access to specified directories.
Claude Text Editor
An MCP server for viewing, editing, and creating text files, based on the Claude built-in text editor tool.
WebP Batch Converter
Batch convert PNG, JPG, and JPEG images to WebP format with options for quality, lossless mode, and multi-threaded processing.
Deep Directory Tree MCP
Visualize directory structures with real-time updates, configurable depth, and smart exclusions for efficient project navigation.
MCP-PROCESS
Provides shell access to execute commands and interact with the local file system.
Java Filesystem & Web MCP Server
An MCP server for LLM agents to perform filesystem operations and access web resources.
mini_mcp
A lightweight plugin to list all files and folders on the current macOS user's desktop.
Synology MCP Server
Manage files and downloads on Synology NAS devices using an AI assistant.
File MCP Server
A server providing comprehensive file system operations, automatically downloaded and built on first use.
Filesystem MCP Server
Perform filesystem operations within specified directories.