Spreadsheet MCP

An MCP server based on TypeScript for operating CSV/XLSX spreadsheet files via LLM or API integration, supporting viewing, filtering, sorting, and updating functions.

Developer tools Research and data #Spreadsheet #Data processing #MCP Protocol #Table tool .TypeScript

rating : 2.5 points

downloads : 27

update time : 2025-04-29

What is Spreadsheet MCP Server?

This is an intelligent tool server specifically designed for processing spreadsheet files. It allows you to view, filter, and sort spreadsheet data through simple commands or API calls, and also update existing XLSX files or create new ones.

How to use Spreadsheet MCP Server?

You just need to start the server through the command-line tool and then send simple JSON-format commands to operate spreadsheet files. There's no need to write complex code or install additional software.

Applicable scenarios

Suitable for scenarios where you need to quickly analyze spreadsheet data without opening Excel; suitable for integration into automated workflows; also suitable for developers to add spreadsheet processing functions to applications.

Main features

Data viewingYou can view the basic information of the spreadsheet and preview the data of the specified number of rows

Data filteringSupports filtering out the row data that meets the requirements by column and condition

Data sortingYou can sort the data in ascending or descending order by the specified column

Data updateYou can add a new worksheet to an existing XLSX file or create a brand-new file

Format supportSupports both common spreadsheet formats, CSV and XLSX

Advantages and limitations

Advantages

No need to install Excel or other spreadsheet software

Can be called via the command line or API, suitable for automated processing

Lightweight and runs quickly

Supports common filtering and sorting operations

Limitations

Currently does not support complex formula calculations

Limited performance in processing large data files

Fewer graphical functions, mainly for data processing

How to use

Start the server

Run the server program in the command line

Send a command

Send a JSON-format command to the server via standard input or API

Get the result

The server will return the processing result in JSON format

Usage examples

Quickly view dataWhen you need to quickly view the content of a spreadsheet file without opening large software

Data filteringFind sales records in a specific region from sales data

Data sortingSort student grades from high to low

Frequently Asked Questions

How large a file can this tool handle?

Which file formats are supported?

Do I need to install Excel?

How to update an existing file?

Related resources

GitHub Repository

Project source code and the latest version

MCP Protocol Documentation

Official documentation of the Model Context Protocol

Example File Set

Various spreadsheet example files for testing

🚀 Spreadsheet MCP Server (@zephyr-mcp/spreadsheet)

A TypeScript-based Model Context Protocol (MCP) server for viewing, filtering, sorting, and updating CSV/XLSX spreadsheet files through LLM or API integration.

✨ Features

View spreadsheet information and preview rows.
Filter rows by columns and conditions.
Sort rows by columns (ascending/descending).
Add new worksheets to existing XLSX files or create new files.
Support for CSV and XLSX files.
Return results as JSON strings containing two-dimensional arrays (for viewing/filtering/sorting).
Technology stack: TypeScript, fastmcp, papaparse, xlsx, zod.

📦 Installation and Usage

This package is designed to be run directly using npx. Typical usage does not require installation.

Prerequisites

Node.js v18+ (LTS version recommended).

Running the MCP Server

Start the server in stdio mode (for integration with tools like Cline):

npx @zephyr-mcp/spreadsheet

The server will start and listen for MCP commands via standard input/output.

🛠️ Development

Setup

Clone the repository:

git clone https://github.com/your-username/spreadsheet-mcp.git # Replace with your repository URL
cd spreadsheet-mcp

Install dependencies:
```
npm install
```

Development

Start the development server:
```
npm run dev
```

🧪 Testing

npm test

🚀 Publishing

Update the package version:
```
npm version major/minor/patch
```
Commit the changes and push to the remote repository.
Build and publish:
```
npm run build
npm publish
```

📁 Project Structure

- src/
  ├── server.ts            # MCP server entry point, tool registration
  └── spreadsheetUtils.ts  # Spreadsheet parsing, filtering, formatting, writing
- tests/
  └── server.test.ts

💻 Usage Examples

Example Tools

view_spreadsheet: View file information and preview a specified number of rows. Returns a JSON string containing file information and preview data (two-dimensional array). The rows parameter specifies the number of preview rows (0 means only headers, default is 10, no maximum limit).
filter_spreadsheet: Filter rows by columns and conditions. Returns a JSON string containing the filtered results (two-dimensional array). The rows parameter specifies the maximum number of rows to return (default is all matching rows, no maximum limit).
sort_spreadsheet: Sort rows by columns. Returns a JSON string containing the sorted results (two-dimensional array). The rows parameter specifies the maximum number of rows to return (default is all rows, no maximum limit).
update_spreadsheet_with_new_sheet: Write data to a new worksheet in an XLSX file.