excel-mcp

Excel MCP Server

A Model Context Protocol (MCP) server for Excel operations with enterprise-grade security and clean architecture. Seamlessly integrates with GitHub Copilot, Cline, and other MCP-compatible tools in VS Code.

Features

• Complete Excel Operations: Read, write, and manipulate Excel files (.xlsx, .xls)
• Clean Architecture: Follows Single Responsibility Principle for maintainability
• Enterprise Security: Robust permission system with path restrictions and access control
• VS Code Integration: Works seamlessly with GitHub Copilot and Cline
• TypeScript: Full type safety with modern ES2022+ features
• Zero Deprecated Dependencies: Uses only current, actively maintained libraries

Quick Start

Installation

# Clone the repository
git clone https://github.com/az-coder-123/excel-mcp.git
cd excel-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Copy example environment file
cp .env.example .env

📌 Đã cấu hình sẵn cho Cline

Server đã được cấu hình và kết nối sẵn với Cline! Xem Hướng dẫn cài đặt chi tiết để biết:

✅ Trạng thái hiện tại: Đã kết nối và hoạt động bình thường

• Server đang chạy: node dist/index.js
• Cấu hình Cline: .cline/mcp_servers.json
• File cấu hình đã sẵn sàng sử dụng

Xem ngay: docs/SETUP_GUIDE.md để biết cách sử dụng

Configuration

Edit .env file to customize permissions:

# Restrict access to specific directories
MCP_ALLOWED_PATHS=/home/user/documents,/workspace

# Block sensitive system directories
MCP_DENIED_PATHS=/etc/*,/sys/*,C:\Windows\*

# Set maximum file size (50MB default)
MCP_MAX_FILE_SIZE=52428800

VS Code Integration

This server works seamlessly with MCP-compatible tools in VS Code. See the dedicated setup guides for detailed configuration instructions:

• Google Antigravity Setup — Configuration for Google Antigravity IDE and agy CLI.
• GitHub Copilot Setup — Configuration for GitHub Copilot Chat in VS Code.
• Cline Setup — Configuration for the Cline extension in VS Code.

Available Tools

For detailed parameter references, see the Tools Reference.

System

Tool	Description
excel_health_check	Check server health, dependencies, and configuration

Workbook Operations

Tool	Description
excel_open_workbook	Open an Excel file for operations
excel_create_workbook	Create a new Excel workbook
excel_save_workbook	Save the workbook to disk
excel_close_workbook	Close an opened workbook
excel_get_workbook_context	Get workbook context and state
excel_export_worksheet_to_new_file	Export worksheet to a new Excel file

Worksheet Operations → Detailed docs

Tool	Description
excel_list_worksheets	List all worksheets in a workbook
excel_add_worksheet	Add a new worksheet
excel_delete_worksheet	Delete a worksheet
excel_rename_worksheet	Rename a worksheet
excel_copy_worksheet	Copy a worksheet
excel_insert_rows	Insert rows at position
excel_delete_rows	Delete rows from position
excel_insert_columns	Insert columns at letter
excel_delete_columns	Delete columns from letter
excel_merge_cells	Merge a cell range
excel_unmerge_cells	Unmerge cells
excel_add_table	Add styled Excel table
excel_add_filter	Add auto-filter to range
excel_remove_filter	Remove auto-filter

Cell Operations → Detailed docs

Tool	Description
excel_read_cell	Read a single cell value
excel_read_range	Read multiple cells
excel_write_cell	Write a value to a cell
excel_write_batch	Write multiple cells at once
excel_get_cell_info	Get detailed cell information (type, formula)
excel_copy_range	Copy a cell range to another location
excel_find_replace	Find and replace text
excel_sort_range	Sort a range ascending/descending
excel_get_named_ranges	List defined named ranges
excel_add_named_range	Create a new named range

Formatting & Styles → Detailed docs

Tool	Category	Docs
excel_set_font_style	Font & Text	→
excel_set_font_name_size	Font & Text	→
excel_set_rich_text	Font & Text	→
excel_set_alignment	Alignment	→
excel_center_text	Alignment	→
excel_set_border	Borders	→
excel_apply_all_borders	Borders	→
excel_apply_outline_border	Borders	→
excel_set_background_color	Colors	→
excel_set_font_color	Colors	→
excel_set_gradient_fill	Colors	→
excel_set_number_format	Number Formats	→
excel_apply_currency_format	Number Formats	→
excel_apply_percentage_format	Number Formats	→
excel_apply_date_format	Number Formats	→
excel_apply_header_style	Style Presets	→
excel_apply_title_style	Style Presets	→
excel_apply_table_style	Style Presets	→
excel_auto_fit_columns	Layout & Dimensions	→
excel_set_column_width	Layout & Dimensions	→
excel_set_row_height	Layout & Dimensions	→
excel_freeze_panes	Layout & Dimensions	→
excel_set_print_area	Layout & Dimensions	→
excel_add_header_footer	Layout & Dimensions	→
excel_add_comment	Notes & Links	→
excel_remove_comment	Notes & Links	→
excel_add_hyperlink	Notes & Links	→
excel_add_data_validation	Validation	→
excel_format_worksheet	Batch Formatting	→
excel_batch_format	Batch Formatting	→

Data Utilities & Analytics → Detailed docs

Tool	Category	Docs
excel_import_csv	CSV Transfer	→
excel_export_csv	CSV Transfer	→
excel_find_duplicates	Duplicates	→
excel_count_unique_values	Duplicates	→
excel_highlight_duplicates	Duplicates	→
excel_remove_duplicates	Duplicates	→
excel_text_to_columns	Transformations	→
excel_flash_fill	Transformations	→
excel_vlookup	Lookups	→
excel_index_match	Lookups	→
excel_create_pivot_table	Pivot Tables	→
excel_get_column_stats	Analytics	→
excel_filter_data	Analytics	→
excel_group_aggregate	Analytics	→
excel_profile_data	Analytics	→
excel_search	Search	→
excel_compare_ranges	Range Comparison	→

Visualizations & Protection → Charts | Protection

Tool	Category	Docs
excel_add_chart	Charts	→
excel_update_chart	Charts	→
excel_delete_chart	Charts	→
excel_list_charts	Charts	→
excel_add_conditional_format	Conditional Formats	→
excel_remove_conditional_format	Conditional Formats	→
excel_add_data_bar	Visual Rules	→
excel_add_color_scale	Visual Rules	→
excel_add_icon_set	Visual Rules	→
excel_protect_worksheet	Protection	→
excel_unprotect_worksheet	Protection	→
excel_protect_cells	Protection	→

Formula Engineering & Auditing → Detailed docs

Tool	Category	Docs
excel_list_formulas	Inventory	→
excel_analyze_formula	Structure Analysis	→
excel_get_dependencies	Dependencies	→
excel_trace_precedents	Precedent Tracing	→
excel_trace_dependents	Dependent Tracing	→
excel_check_circular	Cycle Detection	→
excel_explain_formula	Multi-language Explanation	→
excel_audit_formulas	Automated Audit	→

Accounting & Finance → Detailed docs

Tool	Category	Docs
excel_financial_sum	Financial Calculations	→
excel_financial_average	Financial Calculations	→
excel_running_total	Financial Calculations	→
excel_percentage_of_total	Financial Calculations	→
excel_year_to_date	Financial Calculations	→
excel_accounting_format	Accounting Formats	→
excel_vnd_currency_format	Accounting Formats	→
excel_negative_red_format	Accounting Formats	→
excel_show_zeros_instead_of_empty	Accounting Formats	→
excel_period_comparison	Financial Analysis	→
excel_variance_analysis	Financial Analysis	→
excel_check_balance	Financial Analysis	→
excel_find_anomalies	Financial Analysis	→
excel_calculate_npv	Investment Analysis	→
excel_calculate_irr	Investment Analysis	→
excel_calculate_xirr	Investment Analysis	→
excel_calculate_financial_ratio	Investment Analysis	→
excel_create_amortization_schedule	Loan & Debt	→
excel_create_aging_report	Loan & Debt	→
excel_calculate_tax	Tax & Currency	→
excel_calculate_progressive_tax	Tax & Currency	→
excel_convert_currency	Tax & Currency	→
excel_calculate_depreciation	Asset Depreciation	→

Usage Examples & Reference

• Examples — Practical usage examples for all tool groups
• Reference — Color codes, border styles, font names, AARRGGBB format

Security Features

Permission Levels

• read: Read-only access to Excel files
• write: Create and modify Excel files
• delete: Delete worksheets and clear data
• admin: Full administrative access

Path Restrictions

Configure allowed and denied paths using wildcards:

# Allow only specific directories
MCP_ALLOWED_PATHS=/workspace/*,/home/user/documents/*

# Block sensitive system paths
MCP_DENIED_PATHS=/etc/*,/sys/*,/proc/*,C:\Windows\*

File Size Limits

Prevent processing of excessively large files:

MCP_MAX_FILE_SIZE=52428800  # 50MB

Extension Whitelist

Only process specific file types (configured by default):

• .xlsx - Excel Workbook
• .xls - Excel 97-2003 Workbook
• .xlsm - Excel Macro-Enabled Workbook
• .xlsb - Excel Binary Workbook

Architecture

excel-mcp/
├── src/
│   ├── index.ts                 # Application entry point
│   ├── types/
│   │   └── index.ts            # Type definitions
│   ├── security/
│   │   └── permission-checker.ts # Access control
│   ├── services/
│   │   └── excel-service.ts    # Excel operations
│   ├── tools/
│   │   ├── tool-definitions.ts # Tool schemas
│   │   └── tool-handler.ts     # Tool execution
│   ├── server/
│   │   └── excel-mcp-server.ts # MCP server core
│   └── utils/
│       └── logger.ts           # Logging utility
├── docs/
│   ├── AI_WORKFLOW.md          # AI agent SOP & collaboration guidelines
│   ├── ARCHITECTURE.md         # Architecture details
│   ├── API.md                  # API reference
│   ├── SECURITY.md             # Security guide
│   └── TROUBLESHOOTING.md      # Common issues
└── dist/                       # Compiled JavaScript

Design Principles

1. Single Responsibility: Each class/module has one clear purpose
2. Dependency Injection: Components are loosely coupled
3. Type Safety: Full TypeScript coverage with strict mode
4. Error Handling: Comprehensive error catching and reporting
5. Security First: Permission checks before all operations

Development

Scripts

# Development with hot reload
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

# Clean build artifacts
npm run clean

Project Structure

• src/ - TypeScript source files
• dist/ - Compiled JavaScript output
• docs/ - Documentation
• package.json - Dependencies and scripts
• tsconfig.json - TypeScript configuration

Environment Variables

Variable	Description	Default
MCP_SERVER_NAME	Server identifier	excel-mcp
MCP_SERVER_VERSION	Server version	1.0.0
MCP_LOG_LEVEL	Logging verbosity	info
MCP_ALLOWED_PATHS	Comma-separated allowed paths	All paths
MCP_DENIED_PATHS	Comma-separated denied paths	System paths
MCP_MAX_FILE_SIZE	Maximum file size in bytes	52428800 (50MB)

Troubleshooting

Common Issues

"Permission denied" errors

• Check your MCP_ALLOWED_PATHS configuration
• Ensure the file isn't in a denied path
• Verify you have the required permission level

"Workbook not opened" errors

• Call excel_open_workbook before other operations
• Check that the file path is correct
• Ensure the file isn't corrupted

TypeScript compilation errors

• Run npm install to ensure all dependencies are installed
• Check Node.js version (requires >= 18.0.0)

For more troubleshooting help, see docs/TROUBLESHOOTING.md.

License

MIT License - see LICENSE file for details.

Contributing

Contributions are welcome! Please read our contributing guidelines and code of conduct.

Support

• GitHub Issues: Report bugs
• Documentation: Full docs
• Tools Reference: Tools index