mcp-json-yaml-toml

mcp-json-yaml-toml is a Python-based MCP server that provides a unified, schema-aware interface for reading and safely modifying JSON, YAML, and TOML files. It exposes a set of tools designed to help AI agents and clients perform precise, token-efficient operations on structured data without risking formatting or schema integrity. Core capabilities include data access and mutation (data), advanced transformations (data_query), schema management and validation (data_schema), and data format conversion (data_convert). The server also supports advanced generation controls via LMQL constraints (constraint_validate and constraint_list) to guide generation and prevent invalid modifications. When used with LMQL-guided generation, partial inputs can be validated incrementally, improving reliability and reducing the likelihood of syntax or schema errors during writes. The server discovers relevant schemas from directives in files, in-file schema keys, local IDE configurations, and SchemaStore.org, and it can bind files to specific schemas using the data_schema tool. It runs locally, keeps processing within the client environment, and transparently handles auxiliary assets like yq binaries and cached schemas as needed. A notable behavior is that while reading JSONC (JSON with Comments) files is supported, write operations will strip comments due to underlying library limitations.

To use it, run the MCP server via the CLI entry point exposed by uvx (as shown in the Installation steps). Clients can interact with the server by configuring their MCP client to point at the server under an mcpServers mapping, using the command and arguments described in the configuration. The server supports a range of tools and commands such as data to get/set/delete values at specific paths, data_query for advanced transformations, data_merge for deep merges, and data_convert for cross-format conversions (JSON/YAML/TOML). The available LMQL constraints and guidance features help ensure that generated modifications remain valid with respect to the targeted schema and structure.

Prerequisites:

• Python 3.11 or newer installed
• Network access to install dependencies
• A suitable MCP-compatible client (e.g., Claude Code, Cursor, Windsurf, Gemini 2.0, n8n, etc.)

Step-by-step installation:

1. Clone the repository: git clone https://github.com/bitflight-devops/mcp-json-yaml-toml.git cd mcp-json-yaml-toml

2. Ensure Python 3.11+ is available and that you have uvx installed. If uvx is not installed yet, you can install it via your Python package manager or follow the project’s typical setup in the docs. For example: python -m pip install uvx

3. Install dependencies and set up the environment (handled by uvx at runtime, but you can verify the project is ready): uv sync

4. Run the MCP server via the uvx CLI (as shown in the Getting Started instructions): uvx mcp-json-yaml-toml

Optional: If you are integrating with a Claude Code or other MCP clients, add the server configuration to your client’s MCP config as shown in the README under the "Other MCP Clients" section.

Tips and common considerations:

• The server provides multi-format support (JSON, YAML, TOML) through a unified interface. Conversion to TOML is not supported for complex structures due to yq encoder limitations.
• LMQL integration enables incremental validation of partial inputs, helping to catch errors before committing changes.
• Schema discovery is automatic and can leverage directives, in-file keys like $schema, IDE configs, and SchemaStore.org caches to identify the correct schema for a file.
• JSONC support allows reading and querying with comments preserved, but write operations will strip comments.
• Local-first operation means all processing happens on your machine; no data leaves your environment.
• If you enable or rely on yq for transformations or YAML optimizations, ensure the correct binary is installed and accessible (the server will download or manage binaries as needed).
• When configuring clients, you can bind specific files to schemas using the data_schema tool if automatic discovery isn’t sufficient.

Troubleshooting quick tips:

• If uvx/mcp-json-yaml-toml does not start, verify Python 3.11+ is in use and that uvx is installed and on your PATH.
• If a schema cannot be found, check your local SchemaStore cache or try Directive-based/schema-key detection in the target file.
• For write-related issues with JSONC files, remember that comments will be stripped; you may need to adjust workflows to account for this behavior.