The mcp-json-yaml-toml server provides a token-efficient, schema-aware interface for safely reading, modifying, and validating JSON, YAML, TOML, and JSONC files — all processed locally.
Query structured data (
data_query): Extract, filter, or transform data using yq expressions (e.g.,.name,.items[]) without modifying the file. Supports pagination and custom output formats.Get, set, or delete values (
data): Read/write operations on specific paths using dot-separated key paths. Can retrieve full data, just keys/structure, or schema info. Write operations modify the file on disk.Schema management & validation (
data_schema): Validate files against JSON schemas (from SchemaStore.org or custom sources), associate/disassociate files with schemas, add custom catalogs, and auto-discover schemas via directives, in-file keys, or IDE configs.Convert between formats (
data_convert): Transform files between JSON, YAML, and TOML, returning converted content or writing to an output file. Note: conversion to TOML has limitations for complex structures.Deep merge files (
data_merge): Merge two structured data files where the overlay file's values override the base, with configurable output format and optional file destination.Constraint validation (
constraint_validate/constraint_list): Validate values against LMQL-style constraints (e.g.,YQ_PATH,CONFIG_FORMAT,KEY_PATH,JSON_VALUE) to guide generation and improve reliability.
Formatting and comments are preserved during modifications (except JSONC writes, which strip comments). All processing is local — no data leaves the machine.
Provides token-efficient tools for reading, querying, modifying, and validating TOML files with schema awareness and syntax validation, preventing format errors.
Provides token-efficient tools for reading, querying, modifying, and validating YAML files with schema awareness, preserving comments and formatting while preventing indentation errors.
Click on "Install 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., "@mcp-json-yaml-tomlvalidate my package.json file against npm schema"
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.
Stop AI coding tools from breaking your data files. No more grep guesswork, hallucinated fields, or non-schema-compliant data added to files. This MCP server gives AI assistants a strict, round-trip safe interface for working with structured data.
The Problem
AI coding tools often destroy structured data files:
They grep through huge json, yaml, and toml files (like json logs, or AI transcript files) and guess at keys.
They hallucinate fields that never existed.
They use sed and regex that leave files in invalid states.
They break YAML indentation and TOML syntax.
They can't validate changes before writing.
The Solution
mcp-json-yaml-toml provides AI assistants with proper tools for structured data:
Token-efficient: Extract exactly what you need without loading entire files.
Schema validation: Enforce correctness using SchemaStore.org or custom schemas.
Safe modifications: Enforced validation on write; preserve comments and formatting.
Multi-format: JSON, YAML, and TOML through a unified interface.
Directive-based detection: Support for
# yaml-language-server,#:schema, and$schemakeys in all formats.Constraint-based guided generation: Native LMQL support for proactive validation of partial inputs.
Local-First: All processing happens locally. No data ever leaves your machine.
Transparent JIT Assets: The server auto-downloads
yqif missing and fetches missing schemas from SchemaStore.org for local caching.
JSONC Support: Files with .jsonc extension (JSON with Comments) are fully supported for reading, querying, and schema validation. However, write operations will strip comments due to library limitations.
Getting Started
Prerequisites
Python ≥ 3.11 installed.
An MCP-compatible client (Claude Code, Cursor, Windsurf, Gemini 2.0, n8n, etc.).
Installation
The server uses uvx for automatic dependency management and zero-config execution.
AI Agents & CLI Tools
Claude Code (CLI)
Other MCP Clients
Add this to your client's MCP configuration:
Seedocs/clients.md for detailed setup guides for Cursor, VS Code, and more.
Schema Discovery & Recognition
The server automatically identifies the correct JSON schema for your files using multiple strategies:
Directives: Recognizes
# yaml-language-server: $schema=...and#:schema ...directives.In-File Keys: Detects
$schemakeys in JSON and YAML (also supports quoted"$schema"in TOML).Local IDE Config: Discovers schemas from VS Code/Cursor extension settings and caches.
SchemaStore.org: Performs glob-based auto-detection against thousands of known formats.
Manual Association: Use the
data_schematool to bind a file to a specific schema URL or name.
LMQL & Guided Generation
This server provides native support for LMQL (Language Model Query Language) to enable Guided Generation. This allows AI agents to validate partial inputs (e.g., path expressions) incrementally before execution.
Incremental Validation: Check partial inputs (e.g.,
.data.us) and get the remaining pattern needed.Improved Reliability: Eliminate syntax errors by guiding the LLM toward valid tool inputs.
Rich Feedback: Get suggestions and detailed error messages for common mistakes.
See theDeep Dive: LMQL Constraints for detailed usage examples.
Available Tools
Tool | Description |
| Get, set, or delete values at specific paths |
| Advanced yq/jq expressions for transformations |
| Manage schemas and validate files |
| Convert between JSON, YAML, and TOML |
| Deep merge structured data files |
| Validate inputs against LMQL constraints |
| List available generation constraints |
ConversionTO TOML is not supported due to yq's internal encoder limitations for complex structures.
Development
Setup
Testing
ash
Run all tests (coverage included)
uv run pytest
Avoid--all-files during feature development to keep PR diffs clean and preserve git history.
Project Structure
Code Quality
The project uses prek (a Rust-based pre-commit tool) for unified linting and formatting. AI Agents MUST use the scoped verification command:
Avoid--all-files during feature development to keep PR diffs clean and preserve git history.
Project Structure
Token Efficiency Experiment
Two identical Claude Code sub-agents were given the same task: read ~/.claude.json and report every MCP server listed, including command, args, and env vars.
Setup
Agent A — standard prompt, used the built-in
ReadtoolAgent B — same prompt with one line appended:
You must use the mcp__json-yaml-toml for all file interactions.
Both agents used the sonnet model.
Prompts
Agent A prompt:
Agent B prompt:
Results
Both agents returned identical findings (8 MCP servers with correct configs).
Metric | Agent A (Read tool) | Agent B (mcp-json-yaml-toml) |
Total tokens | 37,119 | 28,734 |
Tool uses | 4 | 2 |
Duration | 29.3s | 12.7s |
Agent B used 22.6% fewer tokens and completed in 43% of the time with half the tool calls.
Why
The Read tool loads the entire file into context. ~/.claude.json is a large file — the agent had to consume all of it to find the mcpServers section. The MCP server's data_query tool extracted just the mcpServers section directly, keeping the context window small.