sheet2json-mcp

An MCP server that lets an AI agent turn messy spreadsheets into clean, validated JSON, on rails.

A lot of engineering and operations data still lives in hand-maintained Excel and CSV files: bills of materials, sensor logs, order lists. Asking an LLM to "just convert it" works until it quietly guesses a value, drops a row or invents a column. This server keeps the AI useful but constrained: the agent decides which file and which schema; deterministic Python code does the conversion and reports every problem.

"Convert pcb_bom_rev_b.xlsx to JSON"
        │
        ▼
  AI agent ──(MCP)──► list_files → inspect_file → convert_file
                                                  │
                     fixed JSON Schemas ──────────┤
                                                  ▼
                       valid records + row-level error report
                       (JSON file written only if every row is valid)

The rails

Related MCP server: ETL-D MCP Server

What it handles

• .xlsx, .xlsm (any sheet) and .csv (auto-detects , ; tab | delimiters, UTF-8 or Windows-1252)

• Messy headers: Part No., MPN and part_number all map to the same field, using aliases defined in the schema

• Danish formats: decimal comma (72,5), dd-mm-yyyy dates, Danish column names (Værdi, Enhed, Antal)

• Type conversion to integer, number, boolean, enum (case-insensitive, returned in canonical form), date and date-time

Tools

Included schemas

• bom: PCB bill of materials (designators, part number, manufacturer, quantity, unit price…)

• sensor_readings: time-stamped temperature / pressure / flow / humidity readings, e.g. from a district heating substation

Adding a schema means dropping a *.schema.json file (standard JSON Schema 2020-12) into the schema folder. Two extra keys are supported: x-aliases on a property (alternative column names) and x-unique-key on the schema (fields that must be unique per row).

Example

examples/data/pcb_bom_rev_b.xlsx has inconsistent headers and three bad rows. Result of convert_file(path="pcb_bom_rev_b.xlsx", schema="bom") (shortened):

{
  "rows_read": 6, "valid_rows": 3, "invalid_rows": 3,
  "column_mapping": { "designators": "Ref Des", "part_number": "Part No.", "quantity": "Qty", "...": "..." },
  "unmapped_columns": ["Notes"],
  "errors": [
    { "row": 5, "field": "quantity", "value": "one", "message": "'one' is not a number" },
    { "row": 6, "field": "part_number", "message": "'part_number' is a required property" },
    { "row": 7, "field": "designators", "message": "Duplicate of row 3 ({'designators': 'C1'})" }
  ],
  "records_preview": [ { "designators": "R1, R2, R5", "part_number": "RC0603FR-0710KL", "quantity": 3, "unit_price_dkk": 0.12, "...": "..." } ]
}

Install

Requires Python 3.10+.

git clone https://github.com/<tony-allex>/sheet2json-mcp.git
cd sheet2json-mcp
pip install -e ".[dev]"
pytest            # 17 tests, including end-to-end tests through a real MCP client

Use with Claude Code

claude mcp add sheet2json \
  --env SHEET2JSON_DATA_DIR=/path/to/your/spreadsheets \
  --env SHEET2JSON_OUTPUT_DIR=/path/to/output \
  -- sheet2json-mcp

Copy skills/sheet2json/ into your skills folder (e.g. .claude/skills/) so the agent follows the workflow.

Use with Claude Desktop (or any MCP client)

{
  "mcpServers": {
    "sheet2json": {
      "command": "sheet2json-mcp",
      "env": {
        "SHEET2JSON_DATA_DIR": "/path/to/your/spreadsheets",
        "SHEET2JSON_OUTPUT_DIR": "/path/to/output"
      }
    }
  }
}

Try it on the examples by pointing SHEET2JSON_DATA_DIR at examples/data (regenerate them with python examples/make_examples.py).

Project layout

src/sheet2json/core.py      conversion logic (no MCP dependency, easy to test and reuse)
src/sheet2json/server.py    MCP tools: a thin layer over core.py
src/sheet2json/schemas/     JSON Schemas (the "rails")
skills/sheet2json/SKILL.md  instructions for the AI agent
tests/                      unit tests + end-to-end MCP tests

Ideas for next steps

• A write_to_database tool (e.g. MongoDB or Azure Cosmos DB) behind the same validation

• Deploy over streamable HTTP in a container (Azure Container Apps) so a team can share one server

• A schema for component data that checks part numbers against a supplier API