CharlieNey/SpreadJS_mcp

SpreadJS MCP Server

A Model Context Protocol (MCP) server for controlling SpreadJS spreadsheets. This project enables AI assistants to interact with Excel-like spreadsheets through a comprehensive set of 86+ tools.

Features

MCP Tools (86+)

Interactive Frontend

• SpreadJS Viewer - Full spreadsheet with cell editing
• Formula Bar - View/edit cell formulas with A1 reference
• Sheet Tabs - Navigate between sheets, add new sheets
• Status Bar - Selection statistics (Sum, Average, Count)
• Undo/Redo - Toolbar buttons for history navigation
• AI Chat Panel - Interact with Claude to manipulate spreadsheets

Prerequisites

• Node.js 18+
• npm 9+
• SpreadJS license key (optional, for production use)

Installation

# Clone the repository
git clone https://github.com/yourusername/SpreadJS_mcp.git
cd SpreadJS_mcp

# Install dependencies
npm install

# Build the project
npm run build

Running the Application

Option 1: MCP Server Only (for AI integration)

# Run the MCP server on stdio
npm start

# Or development mode with auto-reload
npm run dev

Option 2: Full Application (Frontend + Backend + MCP)

# Terminal 1: Start backend API
cd packages/backend && npm run dev

# Terminal 2: Start frontend
cd packages/frontend && npm run dev

# Terminal 3: Start MCP server (optional)
npm run dev

• Frontend: http://localhost:5173
• Backend API: http://localhost:3001

Using with Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "spreadjs": {
      "command": "node",
      "args": ["/path/to/SpreadJS_mcp/dist/index.js"]
    }
  }
}

Using with MCP Inspector

npx @modelcontextprotocol/inspector node dist/index.js

Opens at http://localhost:5173 for testing all tools interactively.

Project Structure

SpreadJS_mcp/
├── src/
│   ├── index.ts              # MCP server entry
│   ├── tools/                # Tool definitions (17 modules)
│   │   ├── cell.ts           # Cell operations
│   │   ├── sheet.ts          # Sheet operations
│   │   ├── workbook.ts       # Workbook operations
│   │   ├── row-col.ts        # Row/column ops
│   │   ├── format.ts         # Formatting
│   │   ├── chart.ts          # Charts
│   │   ├── io.ts             # Import/export
│   │   ├── validation.ts     # Data validation
│   │   ├── conditional.ts    # Conditional format
│   │   ├── table.ts          # Tables
│   │   ├── merge.ts          # Merge & freeze
│   │   ├── named-range.ts    # Named ranges
│   │   ├── comment.ts        # Comments
│   │   ├── sort-filter.ts    # Sort & filter
│   │   ├── find-replace.ts   # Find & replace
│   │   ├── sparkline.ts      # Sparklines
│   │   └── protection.ts     # Protection
│   ├── runtime/
│   │   ├── index.ts          # Runtime manager
│   │   └── session.ts        # Workbook session
│   └── utils/
│       ├── range-parser.ts   # A1 notation parser
│       └── error-handler.ts  # Error helpers
├── packages/
│   ├── frontend/             # React + SpreadJS UI
│   │   └── src/
│   │       ├── App.tsx
│   │       └── components/
│   │           └── SpreadsheetView.tsx
│   └── backend/              # Express API
│       └── src/
│           └── index.ts
└── dist/                     # Compiled output

Environment Variables

Example Usage

Create a spreadsheet with data and formula

1. Use cell_set to add headers: A1="Product", B1="Sales"
2. Use range_set for data: A2:B4 with product/sales data
3. Use cell_set_formula for total: B5="=SUM(B2:B4)"
4. Use format_set_style for header formatting
5. Use workbook_save_json to export

Create a filtered table

1. Use table_create with range A1:D10
2. Use filter_column to filter by criteria
3. Use range_sort to sort by a column

Development

# Build
npm run build

# Watch mode
npm run watch

# Type check
npx tsc --noEmit

# Run frontend dev server
cd packages/frontend && npm run dev

License

MIT

Acknowledgments

• SpreadJS by GrapeCity
• Model Context Protocol by Anthropic