JSON MCP Server

A powerful MCP (Model Context Protocol) server for editing and managing JSON files with dot-notation path access.

Features

• ✅ Read JSON values using dot-separated paths
• ✏️ Set or update JSON values (supports nested structures)
• 🗑️ Delete JSON key-value pairs
• 🔄 Auto-create missing JSON files
• 🌳 Automatically create intermediate nested objects

Installation

# Activate virtual environment
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

Running the Server

python mcp_json.py

The server runs on stdio transport by default, which is the standard for MCP clients like Claude Desktop.

Tools

1. json:get - Get Value

Retrieve a value from a JSON file using a dot-separated key path.

Parameters:

• path: JSON file path (absolute or relative)
• key: Dot-separated key path (e.g., "user.name")

Examples:

json:get(path="data.json", key="name")
json:get(path="config.json", key="database.host")
json:get(path="users.json", key="users.0.name")

2. json:set - Set Value

Set or update a value in a JSON file. Supports JSON strings or plain strings. Automatically creates missing intermediate objects.

Parameters:

• path: JSON file path
• key: Dot-separated key path
• value: Value to set (can be JSON string)

Examples:

json:set(path="data.json", key="name", value="John Doe")
json:set(path="config.json", key="port", value="3000")
json:set(path="config.json", key="database", value='{"host":"localhost","port":5432}')
json:set(path="data.json", key="tags", value='["python","mcp","json"]')
json:set(path="config.json", key="api.endpoints.users", value="/api/v1/users")

3. json:delete - Delete Key

Delete a key from a JSON file using a dot-separated key path.

Parameters:

• path: JSON file path
• key: Dot-separated key path

Examples:

json:delete(path="data.json", key="oldField")
json:delete(path="config.json", key="database.password")
json:delete(path="user.json", key="settings.theme")

Usage Examples

Example 1: Create User Configuration

json:set(path="user.json", key="profile.name", value="John Doe")
json:set(path="user.json", key="profile.email", value="john@example.com")
json:set(path="user.json", key="profile.age", value="30")
json:set(path="user.json", key="settings.theme", value="dark")
json:set(path="user.json", key="settings.notifications", value="true")
json:get(path="user.json", key="profile")

Result user.json:

{
  "profile": {
    "name": "John Doe",
    "email": "john@example.com",
    "age": "30"
  },
  "settings": {
    "theme": "dark",
    "notifications": "true"
  }
}

Example 2: Manage API Configuration

json:set(path="api.json", key="api.baseUrl", value="https://api.example.com")
json:set(path="api.json", key="api.version", value="v2")
json:set(path="api.json", key="api.timeout", value="5000")
json:set(path="api.json", key="endpoints", value='{"users":"/users","posts":"/posts"}')
json:get(path="api.json", key="api")
json:delete(path="api.json", key="endpoints.posts")

Example 3: Working with Arrays

json:set(path="tasks.json", key="tasks", value='[{"id":1,"title":"Learn MCP","done":false}]')
json:get(path="tasks.json", key="tasks.0.title")

MCP Client Configuration

Add this server to your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "json-editor": {
      "command": "python3",
      "args": ["/absolute/path/to/mcp_json.py"],
      "enabled": true
    }
  }
}

Or using the virtual environment Python:

{
  "mcpServers": {
    "json-editor": {
      "command": "/absolute/path/to/venv/bin/python",
      "args": ["/absolute/path/to/mcp_json.py"],
      "enabled": true
    }
  }
}

How It Works

• Dot-notation paths: Use dots (.) to separate nested keys: "user.profile.name"
• Auto-creation: Missing files are created as empty objects {}
• Nested objects: Missing intermediate objects are automatically created
• Value parsing: The value parameter attempts JSON parsing first, falls back to string
• Pretty formatting: JSON files are saved with 2-space indentation

Error Messages

• ❌ Key not found: {key} - When trying to get or delete a non-existent key
• Invalid JSON format: {path} - When the file exists but contains invalid JSON

Development

The server uses FastMCP, which provides:

• Automatic parameter validation
• Built-in error handling
• Support for multiple transports (stdio, SSE, HTTP)

License

MIT