MCP JSON Server

A Model Context Protocol (MCP) server that provides tools for managing JSON data files. This server allows AI assistants like Claude to read, write, query, and manage JSON files in a structured way.

Features

Add JSON Objects: Add new objects to JSON files with automatic ID and timestamp generation
Query Objects: Search for objects by property values
Update Objects: Modify existing objects by index
Delete Objects: Remove objects from JSON files
List Files: View all available JSON files
Retrieve Objects: Get all objects from a specific file

Installation

Option 1: Install from npm

npm install -g jsony-mcp

Option 2: Local Development

git clone https://github.com/vcosmin2701/jsony-mcp
cd mcp-json-server
npm install
npm run build

Configuration

Claude Desktop Configuration

Add the server to your Claude desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "json-manager": {
      "command": "jsony-mcp"
    }
  }
}

For local development: ``json { "mcpServers": { "json-manager": { "command": "node", "args": ["/path/to/mcp-json-server/dist/server.js"] } } } ``

Data Directory

By default, JSON files are stored in ~/.mcp-json-server/data/

You can customize this location using the MCP_JSON_DATA_DIR environment variable:

{
  "mcpServers": {
    "json-manager": {
      "command": "jsony-mcp",
      "env": {
        "MCP_JSON_DATA_DIR": "/custom/path/to/data"
      }
    }
  }
}

Usage

Once configured, Claude can use the following tools:

add_json_object

Add a new object to a JSON file: `` Add to todos.json: {"title": "Buy groceries", "completed": false} ``

get_json_objects

Retrieve all objects from a file: `` Get all items from todos.json ``

query_json_objects

Search for objects by property: `` Find all completed tasks in todos.json ``

update_json_object

Update an object at a specific index: `` Update index 0 in todos.json: set completed to true ``

delete_json_object

Remove an object by index: `` Delete item at index 2 from todos.json ``

list_json_files

List all available JSON files: `` Show me all JSON files ``

Architecture

The server follows clean code principles and SOLID design patterns:

Separation of Concerns: Modular architecture with distinct layers
Dependency Injection: Improved testability and maintainability
Strategy Pattern: Extensible tool handler system
Repository Pattern: Abstracted data access layer
Error Handling: Custom error types with proper propagation

See ARCHITECTURE.md for detailed documentation.

Development

Build

npm run build

Run in Development

npm run dev

Test Locally

npm start

Contributing

Fork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request

License

MIT

Author

Vladut Cosmin

jsony-mcp