# Excel Mcp

> Excel MCP Server: Connect AI agents to Excel/CSV files. Securely read, query, and analyze spreadsheet data for intelligent reporting.

- **Type:** MCP server
- **Install:** `agentstack add mcp-az-coder-123-excel-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [az-coder-123](https://agentstack.voostack.com/s/az-coder-123)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [az-coder-123](https://github.com/az-coder-123)
- **Source:** https://github.com/az-coder-123/excel-mcp

## Install

```sh
agentstack add mcp-az-coder-123-excel-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

```bash
# 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](docs/SETUP_GUIDE.md) để 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](docs/SETUP_GUIDE.md) để biết cách sử dụng

### Configuration

Edit `.env` file to customize permissions:

```env
# 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

#### For GitHub Copilot

Add to your VS Code `settings.json`:

```json
{
  "github.copilot.chat.experimental.mcpServers": {
    "excel-mcp": {
      "command": "node",
      "args": ["/path/to/excel-mcp/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

#### For Cline

Add to your Cline MCP configuration file (`~/.config/cline/mcp_servers.json`):

```json
{
  "mcpServers": {
    "excel-mcp": {
      "command": "node",
      "args": ["/path/to/excel-mcp/dist/index.js"],
      "env": {
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}
```

## Available Tools

### excel_health_check

Check server health, dependencies, and configuration status. This tool is useful for verifying that the MCP server is running correctly and all systems are operational.

```json
{
}
```

**No parameters required**

**Response Example:**
```json
{
  "status": "healthy",
  "server": {
    "name": "excel-mcp",
    "version": "1.0.0",
    "nodeVersion": "v18.0.0",
    "platform": "darwin",
    "arch": "arm64",
    "uptime": "5m 32s"
  },
  "dependencies": {
    "exceljs": "ok",
    "filesystem": "ok",
    "memory": "ok",
    "memoryUsage": {
      "heapUsed": "45MB",
      "heapTotal": "64MB",
      "rss": "78MB",
      "external": "2MB"
    }
  },
  "configuration": {
    "logLevel": "info",
    "maxFileSize": 52428800,
    "maxFileSizeMB": "50MB",
    "allowedPathsCount": 0,
    "deniedPathsCount": 4,
    "allowedExtensions": [".xlsx", ".xls", ".xlsm", ".xlsb"],
    "permissions": ["read", "write", "delete"]
  },
  "tests": {
    "permissionChecker": "pass",
    "logger": "pass",
    "excelOperations": "pass"
  },
  "responseTime": "45ms",
  "timestamp": "2024-03-21T12:34:56.789Z"
}
```

### excel_open_workbook

Open an Excel file for operations.

```json
{
  "filePath": "/path/to/file.xlsx"
}
```

### excel_create_workbook

Create a new Excel workbook.

```json
{
  "filename": "report",
  "outputPath": "/workspace"
}
```

### excel_read_cell

Read a single cell value.

```json
{
  "filename": "report.xlsx",
  "worksheet": "Sheet1",
  "cellAddress": "A1"
}
```

### excel_read_range

Read multiple cells.

```json
{
  "filename": "report.xlsx",
  "worksheet": "Sheet1",
  "startCell": "A1",
  "endCell": "C10"
}
```

### excel_write_cell

Write a value to a cell.

```json
{
  "filename": "report.xlsx",
  "worksheet": "Sheet1",
  "cellAddress": "A1",
  "value": "Hello World"
}
```

### excel_list_worksheets

List all worksheets in a workbook.

```json
{
  "filename": "report.xlsx"
}
```

### excel_add_worksheet

Add a new worksheet.

```json
{
  "filename": "report.xlsx",
  "worksheetName": "Summary"
}
```

### excel_save_workbook

Save the workbook to disk.

```json
{
  "filename": "report.xlsx",
  "outputPath": "/workspace/report-final.xlsx"
}
```

### excel_close_workbook

Close an opened workbook.

```json
{
  "filename": "report.xlsx"
}
```

### excel_get_cell_info

Get detailed cell information including formulas.

```json
{
  "filename": "report.xlsx",
  "worksheet": "Sheet1",
  "cellAddress": "B5"
}
```

## 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:

```env
# 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:

```env
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

```bash
# 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](docs/TROUBLESHOOTING.md).

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Contributing

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

## Support

- GitHub Issues: [Report bugs](https://github.com/az-coder-123/excel-mcp/issues)
- Documentation: [Full docs](docs/)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [az-coder-123](https://github.com/az-coder-123)
- **Source:** [az-coder-123/excel-mcp](https://github.com/az-coder-123/excel-mcp)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-az-coder-123-excel-mcp
- Seller: https://agentstack.voostack.com/s/az-coder-123
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.