zrald1-excel-mcp-server

Excel MCP Server

A comprehensive Model Context Protocol (MCP) server for Excel file operations and manipulation, designed specifically for AI agent integration. This server enables AI assistants like Claude, ChatGPT, and other MCP-compatible agents to create, read, modify, and analyze Excel files with full programmatic control.

🚀 Key Features

📊 Complete Excel Operations

• File Management: Create, open, save, copy, move, and delete Excel files
• Worksheet Operations: Add, remove, rename, and copy worksheets
• Cell Operations: Read, write, format cells with support for formulas and data types
• Table Management: Create, format, and manipulate Excel tables
• Chart Generation: Create various chart types (column, line, pie, bar) with customization
• Formula Support: Set and execute Excel formulas with cross-sheet references

🤖 AI Agent Optimized

• MCP Protocol Compliance: Full Model Context Protocol specification support
• Tool Discovery: All 20+ Excel tools discoverable by AI agents
• Schema Validation: Complete JSON schemas for all parameters
• Error Handling: Informative error messages for AI debugging
• Complex Workflows: Support for multi-step business scenarios

🎯 Production Ready

• High Performance: Handles large datasets (10,000+ rows) efficiently
• Concurrent Support: Multiple AI agents can use simultaneously
• Cross-Platform: Windows, macOS, and Linux compatibility
• Memory Optimized: Efficient memory usage with cleanup mechanisms
• Comprehensive Testing: 500+ test cases with 85%+ code coverage

Features

• File Operations: Create, open, save, move, delete, rename Excel files
• Workbook Management: Properties, protection, and metadata
• Worksheet Operations: Create, delete, rename, copy, move sheets
• Table Management: Create, delete, format, and manipulate tables
• Cell Operations: Read, write, format cells and ranges
• Advanced Features: Charts, pivot tables, conditional formatting
• Formula Support: Calculate and manipulate Excel formulas
• Styling: Comprehensive formatting and styling options

Installation

npm install
npm run build

Usage

npm start

Development

npm run dev
npm run watch  # For continuous compilation

Testing

The Excel MCP Server includes a comprehensive test suite to ensure all functionality works correctly and is production-ready for AI agents.

Test Categories

• Unit Tests: Test individual ExcelService methods in isolation
• Integration Tests: Test MCP tools integration with the protocol
• End-to-End Tests: Test complete workflows and real-world scenarios
• Performance Tests: Test with large datasets and concurrent operations

Running Tests

# Install dependencies
npm install

# Run all tests
npm test

# Run tests with coverage
npm test -- --coverage

# Run specific test categories
npm test tests/unit/          # Unit tests only
npm test tests/integration/   # Integration tests only

# Run tests in watch mode (for development)
npm run test:watch

# Use the comprehensive test runner
node scripts/test-runner.js full    # Complete test suite
node scripts/test-runner.js unit    # Unit tests only
node scripts/test-runner.js coverage # With coverage report

Test Coverage

The test suite maintains high coverage standards:

• Statements: 80%+ coverage
• Branches: 80%+ coverage
• Functions: 80%+ coverage
• Lines: 80%+ coverage

Test Documentation

For detailed testing information, see tests/README.md which includes:

• Test structure and organization
• Writing new tests
• Debugging tests
• Custom matchers
• Performance benchmarks
• Troubleshooting guide

API Documentation

The server exposes the following tools through the MCP protocol:

File Operations

• excel_create_file - Create a new Excel file
• excel_open_file - Open an existing Excel file
• excel_save_file - Save the current workbook
• excel_move_file - Move/rename Excel files
• excel_delete_file - Delete Excel files

Worksheet Operations

• excel_create_sheet - Create a new worksheet
• excel_delete_sheet - Delete a worksheet
• excel_rename_sheet - Rename a worksheet
• excel_copy_sheet - Copy a worksheet
• excel_list_sheets - List all worksheets

Table Operations

• excel_create_table - Create a new table
• excel_delete_table - Delete a table
• excel_format_table - Format table appearance
• excel_add_table_data - Add data to tables

Cell Operations

• excel_read_cells - Read cell values and formatting
• excel_write_cells - Write data to cells
• excel_format_cells - Apply formatting to cells
• excel_set_formula - Set formulas in cells

Advanced Features

• excel_create_chart - Create charts
• excel_create_pivot_table - Create pivot tables
• excel_apply_conditional_formatting - Apply conditional formatting

Validation for AI Agents

The Excel MCP Server has been thoroughly tested to ensure AI agents can successfully:

1. Discover Tools: All MCP tools are properly registered with valid schemas
2. Execute Operations: File, worksheet, cell, and table operations work reliably
3. Handle Errors: Graceful error handling with informative error messages
4. Process Large Data: Efficient handling of large Excel files and datasets
5. Maintain Data Integrity: Consistent data handling across all operations

Example AI Agent Usage

// AI agents can discover available tools
const tools = await mcpServer.listTools();

// Execute file operations
await mcpServer.callTool('excel_create_file', {
  filePath: '/path/to/report.xlsx',
  overwrite: false
});

// Manipulate data
await mcpServer.callTool('excel_write_cells', {
  filePath: '/path/to/report.xlsx',
  sheetName: 'Data',
  range: 'A1:C10',
  data: [/* your data */]
});

// Create visualizations
await mcpServer.callTool('excel_create_chart', {
  filePath: '/path/to/report.xlsx',
  sheetName: 'Data',
  chartType: 'column',
  dataRange: 'A1:B10',
  title: 'Sales Report'
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add comprehensive tests for new functionality
5. Ensure all tests pass: node scripts/test-runner.js full
6. Submit a pull request

Development Workflow

# Set up development environment
npm install
npm run build

# Run tests during development
npm run test:watch

# Before submitting PR
node scripts/test-runner.js full

License

MIT