xspreadsheet (Amanarneja)

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包管理器

安装

1. 克隆存储库：

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

1. 创建虚拟环境：

   python -m venv venv

1. 激活虚拟环境：

   # Windows
   venv\Scripts\activate

   # macOS/Linux
   source venv/bin/activate

1. 安装依赖项：

   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支持

发展

添加新功能

1. Excel库：添加新方法 excel_library.py
2. MCP工具：将新方法作为MCP工具公开 server.py
3. 文档：更新帮助资源和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"]
}

🤝 贡献

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

1. 分叉存储库 在GitHub上
2. 克隆你的叉子 本地：

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

1. 创建要素分支:

   git checkout -b feature/amazing-feature

1. 进行更改 并添加测试
2. 运行验证:

   python verify.py
   python demo.py

1. 提交您的更改:

   git commit -m "Add amazing feature"

1. 推到您的分支:

   git push origin feature/amazing-feature

1. 打开拉取请求 在GitHub上

开发指南

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

📄 许可证

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

🆘 支持和资源

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

🌟 致谢

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

______________________________________________________________________

🚀 准备好用人工智能增强Excel工作流程了吗？今天就开始吧！

](https://github.com/amanarneja/XSpreadsheet) ](https://github.com/amanarneja/XSpreadsheet)