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:

• 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

Workbook Operations

Worksheet Operations

Cell Operations

Formatting → Detailed docs

Accounting & Finance → Detailed docs

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/
│   ├── 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

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