使用说明

Excel MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供Excel文件操作功能。该项目包括一个独立的Excel库和一个MCP服务器，该服务器将Excel操作作为Claude等AI助手的工具。

✨ 特性

📊 Excel操作

读取Excel文件：使用范围和工作表选择从.xlsx和.xls文件中提取数据
编写Excel文件：使用结构化数据和标题创建新的Excel文件
工作表管理：添加、删除和管理多个工作表
细胞操作：用值或公式更新单个单元格和范围
公式支持：应用和计算Excel公式，包括跨表引用
格式化：应用样式、字体、颜色和高级格式选项
图表：通过自定义创建各种图表类型（折线图、条形图、饼图、散点图）

🔧 MCP集成

FastMCP服务器：使用官方MCP SDK实现高性能MCP服务器
资源端点：内置帮助文档和使用示例
工具定义：所有Excel操作都作为MCP工具公开，并带有完整的类型提示
错误处理：全面的错误报告和日志记录

🚀 快速开始

先决条件

Python 3.8或更高版本
pip包管理器

安装

克隆存储库：

git clone https://github.com/amanarneja/XSpreadsheet.git
cd XSpreadsheet

创建虚拟环境：
```
python -m venv venv
```

激活虚拟环境：

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

安装依赖项：
```
pip install -r requirements.txt
```

用法

运行MCP服务器

cd src/excel_mcp_server
python server.py

服务器将启动并监听标准输入/输出上的MCP协议消息。

使用Excel库

from src.excel_mcp_server.excel_library import ExcelLibrary

# Initialize the library
excel_lib = ExcelLibrary()

# Read an Excel file
data = excel_lib.read_excel_file("example.xlsx", "Sheet1")

# Write data to Excel
excel_lib.write_excel_file("output.xlsx", [
    ["Name", "Age", "City"],
    ["John", 30, "New York"],
    ["Jane", 25, "Boston"]
], headers=["Name", "Age", "City"])

可用的MCP工具

核心业务

read_excel_file
- 从Excel文件读取数据
- 参数： file_path, sheet_name （可选）， range （可选）
write_excel_file
- 将数据写入Excel文件
- 参数： file_path, data, sheet_name （可选）， headers （可选）
get_worksheet_info
- 获取有关工作表的信息
- 参数： file_path

工作表管理

add_worksheet
- 添加新工作表
- 参数： file_path, sheet_name

细胞操作

update_cell
- 更新特定单元格
- 参数： file_path, sheet_name, cell, value
apply_formula
- 应用Excel公式
- 参数： file_path, sheet_name, cell, formula

格式和图表

format_cells
- 应用单元格格式
- 参数： file_path, sheet_name, range, format_options
create_chart
- 创建图表和图形
- 参数： file_path, sheet_name, data_range, chart_type, title （可选）， position （可选）

MCP资源

excel://help -全面的帮助文档
excel://examples -使用示例和代码片段

配置

VS代码集成

该项目包括用于MCP调试的VS代码配置：

{
  "servers": {
    "excel-mcp-server": {
      "type": "stdio",
      "command": "python",
      "args": ["src/excel_mcp_server/server.py"]
    }
  }
}

Claude桌面集成

要与Claude Desktop一起使用，请将此添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "excel-mcp-server": {
      "command": "python",
      "args": ["path/to/XSpreadsheet/src/excel_mcp_server/server.py"],
      "cwd": "path/to/XSpreadsheet"
    }
  }
}

Windows示例：

{
  "mcpServers": {
    "excel-mcp-server": {
      "command": "python",
      "args": ["C:\\projects\\XSpreadsheet\\src\\excel_mcp_server\\server.py"],
      "cwd": "C:\\projects\\XSpreadsheet"
    }
  }
}

替代方案：模块执行

{
  "mcpServers": {
    "excel-mcp-server": {
      "command": "python",
      "args": ["-m", "src.excel_mcp_server.server"],
      "cwd": "path/to/XSpreadsheet"
    }
  }
}

项目结构

Xpreadsheet/
├── src/
│   └── excel_mcp_server/
│       ├── __init__.py
│       ├── server.py           # MCP Server implementation
│       └── excel_library.py    # Core Excel functionality
├── .vscode/
│   └── mcp.json               # VS Code MCP configuration
├── .github/
│   └── copilot-instructions.md # Copilot development guidelines
├── requirements.txt           # Python dependencies
└── README.md                 # This file

依赖项

主控程序：模型上下文协议SDK
openpyxl：Excel文件操作
熊猫：数据处理和分析
anyio：异步I/O支持

发展

添加新功能

Excel库：添加新方法 excel_library.py
MCP工具：将新方法作为MCP工具公开 server.py
文档：更新帮助资源和README

🧪 测试与演示

运行演示

python demo.py

这将创建演示所有功能的示例Excel文件。

验证安装

python verify.py

测试单个组件

# Test the Excel library
python -c "from src.excel_mcp_server.excel_library import ExcelLibrary; print('✅ Library works!')"

# Test the MCP server (press Ctrl+C to stop)
python src/excel_mcp_server/server.py

📖 使用示例

用Claude读取Excel数据

配置后，您可以询问Claude：

从我的sales.xlsx文件中读取数据，该文件名为“Q1数据”，范围A1:D10

克劳德将使用 read_excel_file 工具：

{
  "file_path": "sales.xlsx",
  "sheet_name": "Q1 Data", 
  "range": "A1:D10"
}

用Claude创建图表

“根据我的data.xlsx文件创建一个折线图，显示销售趋势。使用‘销售’表上A1:B12的数据”

克劳德将使用 create_chart 工具：

{
  "file_path": "data.xlsx",
  "sheet_name": "Sales",
  "data_range": "A1:B12",
  "chart_type": "line",
  "title": "Sales Trend"
}

编写Excel文件

使用以下数据创建一个名为'report.xlsx'的新Excel文件：[['Name'，'Score']，['Alice'，95]，['Bob'，87]]

克劳德将使用 write_excel_file 工具：

{
  "file_path": "report.xlsx",
  "data": [["Alice", 95], ["Bob", 87]],
  "headers": ["Name", "Score"]
}

🤝 贡献

我们欢迎捐款！以下是如何开始：

分叉存储库 在GitHub上

克隆你的叉子 本地：

git clone https://github.com/amanarneja/XSpreadsheet.git

创建要素分支:

git checkout -b feature/amazing-feature

进行更改 并添加测试
运行验证:
```
python verify.py
python demo.py
```
提交您的更改:
```
git commit -m "Add amazing feature"
```

推到您的分支:

git push origin feature/amazing-feature

打开拉取请求 在GitHub上

开发指南

遵循现有的代码样式和模式
为所有函数添加类型提示
包含新方法的文档字符串
更新测试和文档
确保所有演示脚本仍然有效

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🆘 支持和资源

问题: GitHub问题
MCP文件: 模型上下文协议
克劳德桌面: 人物克劳德
Excel库：内置 openpyxl

🌟 致谢

使用模型上下文协议（MCP）
Excel操作由 openpyxl
数据处理熊猫