JXLS

You operate a specialized MCP server that generates Excel templates compliant with the JXLS standard. It supports JSON objects and arrays as data inputs, runs over the MCP protocol in stdio mode, and includes strict input validation and path security to prevent traversal attacks. This guide teaches you how to install, run, and use the server to produce ready-to-use JXLS templates for your data needs.

How to use

To generate an JXLS template, first start the MCP server locally. Then, from your MCP client, invoke the template generation tool with the appropriate data structure and format. You can either supply a JSON data structure or an array-based data structure. The server will return a path to the generated template along with JXLS annotations you can review.

Common usage patterns include creating a template for a list of items in JSON format or for a list represented as an array of rows. You can also include data fields that are not bound to data, which will render as empty cells in the data region to support static or manual-entry columns.

When you launch the server, you have access to a tool named generateJxlsTemplate. You supply the templateName, a dataStruct that describes how to map data fields to columns, a dataFormat that selects either json or array, and optional sampleData for validation. The server returns a success flag, the path to the generated template, and the JXLS annotations needed to reproduce the template within Excel.

How to install

Prerequisites you need are Python and a runtime tool for MCP execution. Ensure you have your environment prepared and the necessary tools available on your system before proceeding.

uv sync

uv run jxls-mcp-server

# or call via MCP client with the appropriate command and parameters as shown in examples

Configuration and security notes

The server writes generated templates to a designated output directory. By default, the directory is ./templates. You can override this with an environment variable JXLS_OUTPUT_DIR. The server enforces strict input validation and blocks path traversal attempts to protect your file system.

Paths that do not include an extension or do not point to an existing file are treated as directories. The server will auto-create missing directories and generate a file name using the template name and a timestamp when a directory path is provided.

Examples and data structures

JSON data structure example defines a collection and fields to bind to columns. You may include a field to render a column with data from your object or leave a column unbound for static content.

Array data structure example defines column indices for binding. You can map the first three columns to array positions while allowing other columns to remain unbound for static entries.

API reference for the MCP tool

The tool generateJxlsTemplate requires a templateName, a dataStruct describing data binding, and a dataFormat value of json or array. An optional sampleData array can be provided to validate the template before generation. The server returns a structured response including the path to the generated template and JXLS annotations.

{
  "templateName": "sales_report",
  "dataStruct": {
    "collectName": "sales",
    "itemVariable": "sale",
    "dataFields": [
      {"name": "Product", "field": "product"},
      {"name": "Amount", "field": "amount"},
      {"name": "Date", "field": "date"}
    ]
  },
  "dataFormat": "json",
  "sampleData": [ {"product": "Product A", "amount": 1000, "date": "2024-01-01"} ]
}

Environment and runtime details

The server uses the JXLS output directory configuration and supports security measures to prevent directory traversal in provided paths. The runtime command to start the server, as shown, is the standard way to run the MCP server in stdio mode.

Notes on data bindings and new features

Starting with v1.1.0, you can create columns that do not bind to data. This means you can have static columns (like serial numbers or fixed text), manual-entry columns (for notes or approvals), or calculation columns that Excel computes. If both field and index are empty for a column, that column will render as an empty cell in the data rows.

Available tools

generateJxlsTemplate

Generates an Excel template using JXLS through the MCP server given a template name, a data structure, and a data format