Spreadsheet MCP

🚀 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

1. Clone the repository:

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

2. Install dependencies:

   npm install
   

Development

3. Start the development server:

   npm run dev
   

🧪 Testing

npm test

🚀 Publishing

1. Update the package version:

   npm version major/minor/patch
   

2. Commit the changes and push to the remote repository.
3. 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.

📄 License

MIT License © 2025 Zephyr

👨‍💻 Author

Zephyr