JSON Editor MCP
A Model Context Protocol (MCP) server for editing JSON files with read, write, and deep merge capabilities. Perfect for managing multilingual Next.js projects and other JSON-based configurations.
Note: This is an actively developed tool. Feature requests and bug reports are welcome! File issues on GitHub.
Problems This Solves
- 💰 Significant token savings: Edit specific JSON paths instead of reading/writing entire files
- ⚡ Efficient operations: ~100 tokens per edit vs 4,000+ tokens for full file operations
- 📦 Handles large files: Large translation files may not fit into context windows; targeted operations work regardless of file size
- 🚀 Faster edits: Avoids slow network round-trips from reading/writing entire files
- 🔑 Prevents duplicate keys: AI can't see full translation JSON and creates duplicates; targeted operations avoid this issue
- 🔍 Targeted reads: Read only the values you need using dot notation paths
- ✏️ Targeted writes: Update only specific paths, automatically creates missing nested structures
- 🗑️ Targeted deletes: Remove specific paths from JSON files
- 🔀 Deep merge support: Merge duplicate keys with recursive object merging
- 📚 Multi-file operations: Read, write, or delete the same path from multiple JSON files efficiently
- 📘 TypeScript support: Full type definitions included
- 🤖 MCP compliant: Works with AI assistants (Cursor, Claude, ChatGPT) and development tools
Installation
bun add json-editor-mcp
Usage
MCP Server Configuration
Add to your MCP client configuration:
{
"mcpServers": {
"json-editor": {
"command": "bunx",
"args": ["json-editor-mcp"]
}
}
}
Cursor Rules Integration
Copy the rule file to your project to ensure AI assistants use MCP tools:
cp .cursor/rules/json-editor-mcp.mdc /path/to/your/project/.cursor/rules/
Tools
read_multiple_json_values
Reads the same dot notation path from one or more JSON files in a single operation. Returns a map with file paths as keys and the extracted values as values. Useful for comparing translations across language files or reading from a single file.
Note: For single file operations, pass an array with one file path: ["messages/en.json"]
Input JSON files:
messages/en.json:
{
"common": {
"welcome": "Welcome"
}
}
messages/es.json:
{
"common": {
"welcome": "Bienvenido"
}
}
Tool call:
read_multiple_json_values(["messages/en.json", "messages/es.json"], "common.welcome")
Output:
{
"messages/en.json": "Welcome",
"messages/es.json": "Bienvenido"
}
Single file example:
read_multiple_json_values(["messages/en.json"], "common.welcome")
Output:
{
"messages/en.json": "Welcome"
}
write_json_values
Writes a value to a JSON file at a specified dot notation path. Automatically creates missing nested paths and preserves existing structure.
Input JSON (messages/en.json):
{
"common": {
"welcome": "Welcome"
}
}
Tool call:
write_json_values("/absolute/path/to/messages/en.json", "pages.about.title", "About Us")
Output JSON (messages/en.json):
{
"common": {
"welcome": "Welcome"
},
"pages": {
"about": {
"title": "About Us"
}
}
}
Output:
Successfully wrote to /absolute/path/to/messages/en.json
delete_multiple_json_values
Deletes a value at a specified dot notation path from one or more JSON files. Returns a map with file paths as keys and deletion results as values.
Note: For single file operations, pass an array with one file path: ["messages/en.json"]
Input JSON files:
messages/en.json:
{
"common": {
"welcome": "Welcome",
"goodbye": "Goodbye"
}
}
messages/es.json:
{
"common": {
"welcome": "Bienvenido",
"goodbye": "Adiós"
}
}
Tool call:
delete_multiple_json_values(["messages/en.json", "messages/es.json"], "common.goodbye")
Output:
{
"messages/en.json": "Successfully deleted",
"messages/es.json": "Successfully deleted"
}
Output JSON files:
messages/en.json:
{
"common": {
"welcome": "Welcome"
}
}
messages/es.json:
{
"common": {
"welcome": "Bienvenido"
}
}
merge_duplicate_keys
Performs a deep merge of duplicate keys in a JSON file. Primitives use last-value-wins, objects merge recursively, and arrays use last-value-wins. Useful when AI assistants create duplicate keys because they can't see the full file structure.
Input JSON (messages/en.json):
{
"common": {
"welcome": "Welcome"
},
"common": {
"goodbye": "Goodbye"
}
}
Tool call:
merge_duplicate_keys("messages/en.json")
Output JSON (messages/en.json):
{
"common": {
"welcome": "Welcome",
"goodbye": "Goodbye"
}
}
API Reference
Path Notation: Dot notation for nested paths (e.g., "common.welcome", "pages.home.title")
Error Handling:
- File not found: Creates empty object
{}for reads - Invalid JSON: Returns error message
- Path not found: Error for reads, auto-creates for writes
Deep Merge: Primitives last-value-wins, objects merge recursively, arrays last-value-wins
Development
git clone https://github.com/peternagy1332/json-editor-mcp.git
cd json-editor-mcp
bun install
bun run build
License
MIT License - see LICENSE file for details.
Support
File issues on GitHub.