Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@jsony-mcp Add a new note to notes.json: {'content': 'Meeting at 3pm'}"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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
Related MCP server: MCP JSON Maker
npm install -g jsony-mcpgit clone https://github.com/vcosmin2701/jsony-mcp
cd mcp-json-server
npm install
npm run buildAdd 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:
{
"mcpServers": {
"json-manager": {
"command": "node",
"args": ["/path/to/mcp-json-server/dist/server.js"]
}
}
}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"
}
}
}
}Once configured, Claude can use the following tools:
Add a new object to a JSON file:
Add to todos.json: {"title": "Buy groceries", "completed": false}Retrieve all objects from a file:
Get all items from todos.jsonSearch for objects by property:
Find all completed tasks in todos.jsonUpdate an object at a specific index:
Update index 0 in todos.json: set completed to trueRemove an object by index:
Delete item at index 2 from todos.jsonList all available JSON files:
Show me all JSON filesThe 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.
npm run buildnpm run devnpm startFork the repository
Create a feature branch
Commit your changes
Push to the branch
Create a Pull Request
MIT
Vladut Cosmin
Add a JSON object to a specified file
| Name | Required | Description | Default |
|---|---|---|---|
| object | Yes | JSON object to add | |
| filename | Yes | Name of the JSON file (with .json extension) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavioral traits. It only says 'Add' without explaining whether the operation appends, overwrites, requires the file to already exist, or how duplicates are handled. For a mutation tool, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that is front-loaded with the core action. No wasted words, making it appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations. The description does not explain return values, error behavior, or side effects like file creation. Given the nested object parameter and CRUD sibling context, this is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and both parameters have clear descriptions. The description does not add additional meaning beyond the schema—it merely restates the action. Baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Add a JSON object') and the resource ('a specified file'). It distinguishes from siblings like update_json_object and delete_json_object by using 'add' as the verb, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for adding new objects, but provides no explicit guidance on when to use this tool versus alternatives like update_json_object or delete_json_object. No exclusions or context are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a JSON object by index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index of the object to delete | |
| filename | Yes | Name of the JSON file (with .json extension) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden but does not disclose behavioral details like in-place file modification, irreversibility, or handling of out-of-bounds index. It only states the action without side-effect context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that directly states the action and target. It avoids waste, though it lacks supplementary context; it is appropriately sized for a simple operation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema and no annotations, the description leaves out important context like return value or error behavior. However, the schema fully covers the parameters, and the operation is conceptually simple, making the description minimally viable but not rich.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Both parameters are fully described in the schema (filename and index). The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate given 100% schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'delete' and identifies the resource 'JSON object' with the method 'by index'. This clearly distinguishes it from sibling tools like add, get, query, and update.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. It does not specify prerequisites such as file existence or valid index, nor does it mention when to prefer a different tool. Usage is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve all objects from a JSON file
| Name | Required | Description | Default |
|---|---|---|---|
| filename | Yes | Name of the JSON file (with .json extension) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly indicates a read operation ('retrieve') and scopes to all objects, but it doesn't disclose error handling, return format, or confirm non-destructive behavior explicitly. This is adequate but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence that immediately states the action and scope. There is no wasted wording, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read tool with one parameter and no output schema, the description is nearly complete. It could mention return format or error behavior, but the context is sufficient for an agent to understand the tool's basic function and role among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% coverage for the single parameter 'filename' with a clear description. The tool description adds no additional meaning beyond the schema, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description 'Retrieve all objects from a JSON file' uses a specific verb (retrieve) and clearly identifies the resource (objects from a JSON file). It also distinguishes itself from sibling tools like query_json_objects by explicitly stating 'all' objects, implying no filtering.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you need all objects from a JSON file, but it does not explicitly mention alternatives or when not to use it. For example, it doesn't say 'for filtered queries, use query_json_objects instead,' leaving the differentiation to implication.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all available JSON files
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose behavior. It only states the operation is listing files, but doesn't mention return format, whether it's read-only, pagination, or performance implications. This is a minimal behavioral disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no filler. It directly states the tool's function, making it efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a list-only tool with no params and no output schema, the description gives the core purpose but lacks detail on the return value (e.g., file names, paths) or any usage context. It's minimally complete but leaves the agent guessing about the result format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the empty schema fully covers parameter space. The description doesn't need to explain any parameters, and this is sufficient.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('list') and resource ('JSON files'), clearly distinguishing it from sibling tools that add/get/query/update/delete JSON objects. The scope 'all available' adds clarity about the operation's extent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like query_json_objects or get_json_objects. No context is given about typical use cases or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Query JSON objects based on property values
| Name | Required | Description | Default |
|---|---|---|---|
| value | Yes | Value to search for (can be string, number, boolean) | |
| filename | Yes | Name of the JSON file (with .json extension) | |
| property | Yes | Property name to search by |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full responsibility for behavioral disclosure. It does not explain whether the query is exact or partial match, returns one or all matching objects, how missing properties are handled, or whether it is a read-only operation. This leaves significant behavioral ambiguity.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that immediately conveys the core action, with no fluff or redundancy. It is appropriately sized for a simple query tool, though it sacrifices detail for brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the absence of an output schema and annotations, the description should clarify what the query returns (e.g., matching objects, count, success/failure) and the matching semantics. The current description is too sparse to fully specify the tool's behavior, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
All three parameters (filename, property, value) have descriptions in the schema, achieving 100% schema coverage. The description adds no additional parameter semantics beyond what the schema already provides, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a query operation on JSON objects based on property values, which distinguishes it from sibling mutation tools like add/update/delete. However, it does not explicitly mention that it returns matching objects, so there is slight ambiguity about the exactly returned output.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus siblings such as get_json_objects or list_json_files. No exclusions or alternative recommendations are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a JSON object by index
| Name | Required | Description | Default |
|---|---|---|---|
| index | Yes | Index of the object to update | |
| updates | Yes | Properties to update | |
| filename | Yes | Name of the JSON file (with .json extension) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, so the description carries full responsibility for disclosing side effects. It does not state whether the file is modified, how out-of-bounds indexes are handled, or whether updates are merged or replace existing properties. This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with no redundant words, front-loading the action and target. It is appropriately concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool lacks an output schema and annotations, and the description does not cover important details such as file path resolution, index semantics, or error behavior. The sibling tools give context but the description alone is insufficient for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already provides descriptions for all three parameters, and the description adds no new meaning beyond the phrase 'by index', which echoes the schema. With 100% schema coverage, the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the action (update) and resource (JSON object) with a locator (by index), distinguishing it from siblings like add/delete/query/list. It is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives, such as needing to retrieve the index first via get_json_objects or using delete/add instead. No prerequisites or exclusions are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.4add_json_objectdelete_json_objectget_json_objectslist_json_filesquery_json_objectsupdate_json_objectScored across 6 tools
Each tool targets a distinct operation: add, get all, query, update, delete, and list files. There is no overlap in purpose; even get_json_objects and query_json_objects are clearly different (retrieve all vs. filter by properties).
All tool names follow a consistent verb_noun pattern: add_json_object, get_json_objects, query_json_objects, update_json_object, delete_json_object, list_json_files. The use of singular/plural is logical (action on single vs. multiple).
Six tools is well-scoped for a JSON file management server, covering essential CRUD operations plus query and file listing without unnecessary bloat.
The core CRUD lifecycle is covered: add, get, update, delete, plus query and list files. A minor gap is the lack of a dedicated get-by-index or file deletion, but these can be worked around with existing tools.
Zero-key temporary JSON database for agents: one tool call, no signup, no OAuth, no API keys.
Database for your AI agent. Turn its output into data, docs, skills, and apps you can actually use.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
