Overview

Excel and CSV to JSON MCP Server exposes a lightweight Model Context Protocol (MCP) implementation to convert spreadsheet data into structured JSON. It supports two MCP tools: one for converting pasted tab-separated or comma-separated text and one for fetching an .xlsx file from a URL and converting each sheet into JSON. This server is useful when you need standardized, programmatic spreadsheet-to-JSON conversion inside an MCP-enabled workflow (for example, connecting a UI or AI agent to a data-conversion tool).

The MCP server ships as an npx-executable process and can be wired into MCP-capable clients. A free tier is available for quick tests (row limit applied); a Pro mode unlocks full processing via a proCode environment variable.

Repository: https://github.com/he-yang/excel-to-json-mcp
Tags: developer-tools, excel, json, mcp, wtsolutions

Features

Convert tab-separated (Excel copy/paste) or comma-separated (CSV) text into JSON.
Convert remote .xlsx files (each sheet → JSON object) by URL.
Keeps header row as property keys and maps following rows to JSON objects.
Supports output modes (flat vs nested keys) and header-from-row or header-from-column options.
Simple npx-based server integration for MCP clients.
Free tier for development with a small-row processing limit; Pro mode by environment variable for full datasets.

Installation / Configuration

No installation is required: the server is intended to be run via npx and configured in your MCP client configuration.

Example mcpServers configuration (free version; limited to processing up to 6 rows):

{
  "mcpServers": {
    "excel-to-json-mcp": {
      "command": "npx",
      "args": ["excel-to-json-mcp"]
    }
  }
}

Example mcpServers configuration (Pro, requires a valid proCode):

{
  "mcpServers": {
    "excel-to-json-mcp": {
      "command": "npx",
      "args": ["excel-to-json-mcp"],
      "env": {
        "proCode": "your-pro-code-here"
      }
    }
  }
}

Notes:

SSE and Streamable HTTP modes are not supported since v1.3.0.
Run the server via your MCP client orchestration; npx will download and run the package on demand.

Available Tools

The MCP server exposes two tools. Use them via the MCP tools interface (tool name, parameters object).

excel_to_json_mcp_from_data
- Purpose: Convert tab-separated Excel text or comma-separated CSV text into JSON.
excel_to_json_mcp_from_url
- Purpose: Download an .xlsx file at a given URL and convert each sheet into JSON.

Parameters

excel_to_json_mcp_from_data

Parameter	Type	Required	Description
data	string	Yes	Tab-separated or comma-separated text. Must include header row and at least one data row.
options	object	No	Optional conversion settings (see Options Object).

excel_to_json_mcp_from_url

Parameter	Type	Required	Description
url	string	Yes	HTTP(S) URL to an .xlsx file.
options	object	No	Optional conversion settings (see Options Object).

Options Object

The optional options object customizes output. Pro subscription (proCode) is required for processing larger datasets and advanced options.

Property	Type	Default	Description
proCode	string	“”	Subscription code to lift limits.
jsonMode	string	“flat”	“flat” (default) or “nested”. In nested mode delimiters in headers form nested objects.
header	string	“row”	“row” to use first row as header, or “column” to use first column as header.
delimiter	string	“.”	Delimiter used for nested keys when jsonMode is “nested”.

Example options snippet:

{
  "options": {
    "proCode": "xxxx-xxxx",
    "jsonMode": "nested",
    "header": "row",
    "delimiter": "."
  }
}

Limitations:

Without a valid proCode, data processing is limited (e.g., up to 6 rows).
URL endpoint must point to a .xlsx file for excel_to_json_mcp_from_url.

Use Cases

Quick CSV/Excel snippet conversion (local/paste)
- Prompt your MCP client to call excel_to_json_mcp_from_data with a copied Excel selection (tab-separated) or CSV string.
- Example data:
```
Name	Age	IsStudent
John Doe	25	false
Jane Smith	30	true
```
- Expected output (flat JSON array):
```
[
  {"Name":"John Doe","Age":"25","IsStudent":"false"},
  {"Name":"Jane Smith","Age":"30","IsStudent":"true"}
]
```

Remote Excel workbook conversion

Call excel_to_json_mcp_from_url with url=https://tools.wtsolutions.cn/example.xlsx

Each sheet becomes an object:

[
  {
    "sheetName": "Sheet1",
    "data": [ { "ColumnA": "value1", "ColumnB": "value2" }, ... ]
  },
  ...
]

Integrating into an AI assistant workflow
- Use the MCP tool to preprocess tabular data for downstream semantic analysis, prompting an LLM with a structured JSON payload rather than raw CSV.
Batch conversion in automation
- Chain MCP calls where an upstream service provides file URLs; convert each file to JSON and feed results into ETL or analytics pipelines.

Examples

Call payload (pseudo-MCP tool invocation):

{
  "tool": "excel_to_json_mcp_from_data",
  "params": {
    "data": "Name,Age\nAlice,28\nBob,32",
    "options": {"jsonMode":"flat"}
  }
}

Response: JSON array of objects representing rows with header keys.

Troubleshooting and Notes

Ensure the header row exists; otherwise keys cannot be inferred.
For nested JSON, use consistent header naming (e.g., “address.city”) and set jsonMode to “nested”.
Free tier is convenient for testing, but production use typically requires a proCode for larger files.
SSE / Streamable HTTP are unsupported; run via stdio (npx) as shown in configuration examples.

For source, issues and further docs, see the repository: https://github.com/he-yang/excel-to-json-mcp