Xlwings MCP Server

🚀 xlwings-mcp-server

这是一个强大的模型上下文协议（MCP）服务器，借助xlwings实现Excel自动化操作。该服务器通过基于会话的架构，提供全面的Excel文件操作功能，旨在实现高性能且可靠的Excel操作。

🚀 快速开始

1. 基础用法

启动MCP服务器：

xlwings-mcp-server

或者直接运行：

python -m xlwings_mcp

2. 基于会话的工作流程

# 使用MCP客户端的示例
import mcp

# 打开一个工作簿会话
session_result = client.call_tool("mcp__xlwings-mcp-server__open_workbook", {
    "filepath": "C:/path/to/your/file.xlsx",
    "visible": False,
    "read_only": False
})

session_id = session_result["session_id"]

# 写入数据
client.call_tool("mcp__xlwings-mcp-server__write_data_to_excel", {
    "session_id": session_id,
    "sheet_name": "Sheet1",
    "data": [["Name", "Age", "Score"], ["Alice", 25, 95], ["Bob", 30, 87]]
})

# 应用公式
client.call_tool("mcp__xlwings-mcp-server__apply_formula", {
    "session_id": session_id,
    "sheet_name": "Sheet1",
    "cell": "D2",
    "formula": "=B2+C2"
})

# 创建图表
client.call_tool("mcp__xlwings-mcp-server__create_chart", {
    "session_id": session_id,
    "sheet_name": "Sheet1",
    "data_range": "A1:C3",
    "chart_type": "column",
    "target_cell": "E1"
})

# 关闭会话
client.call_tool("mcp__xlwings-mcp-server__close_workbook", {
    "session_id": session_id
})

✨ 主要特性

核心功能

• 基于会话的架构：持久的Excel工作簿会话，实现最佳性能。
• 全面的Excel操作：全面支持数据操作、公式、格式设置和可视化。
• 线程安全操作：通过每个会话的锁机制实现并发访问。
• 自动资源管理：基于TTL的会话清理和LRU淘汰策略。
• 零错误设计：遵循凯瑟琳·约翰逊原则，具备全面的错误处理。

Excel操作

• 工作簿管理：打开、创建、列出和关闭Excel工作簿。
• 工作表操作：创建、复制、重命名和删除工作表。
• 数据操作：读取、写入和修改Excel数据，支持所有数据类型。
• 公式支持：应用和验证Excel公式，并进行语法检查。
• 高级格式设置：单元格样式、条件格式和区域格式设置。
• 可视化：创建多种类型的图表。
• 表格操作：原生Excel表格的创建和管理。
• 区域操作：单元格合并、复制和删除。

📦 安装指南

先决条件

• Python 3.10 或更高版本
• Windows操作系统（xlwings COM集成所需）
• 已安装Microsoft Excel

使用pip安装

pip install xlwings-mcp-server

从源代码安装

git clone https://github.com/yourusername/xlwings-mcp-server.git
cd xlwings-mcp-server
pip install -e .

使用uv安装（推荐）

uv add xlwings-mcp-server

📚 详细文档

配置

环境变量

# 会话管理
EXCEL_MCP_SESSION_TTL=600          # 会话TTL（秒）（默认值：600）
EXCEL_MCP_MAX_SESSIONS=8           # 最大并发会话数（默认值：8）
EXCEL_MCP_DEBUG_LOG=1              # 启用调试日志（默认值：0）

# Excel设置
EXCEL_MCP_VISIBLE=false            # 显示Excel窗口（默认值：false）
EXCEL_MCP_CALC_MODE=automatic      # 计算模式（默认值：自动）

MCP配置（.mcp.json）

{
  "name": "xlwings-mcp-server",
  "version": "1.0.0",
  "transport": {
    "type": "stdio"
  },
  "tools": {
    "prefix": "mcp__xlwings-mcp-server__"
  }
}

API参考

会话管理

• open_workbook(filepath, visible=False, read_only=False)：创建新会话
• close_workbook(session_id)：关闭会话并保存工作簿
• list_workbooks()：列出活动会话
• force_close_workbook_by_path(filepath)：按文件路径强制关闭

数据操作

• write_data_to_excel(session_id, sheet_name, data, start_cell=None)
• read_data_from_excel(session_id, sheet_name, start_cell=None, end_cell=None)
• apply_formula(session_id, sheet_name, cell, formula)
• validate_formula_syntax(session_id, sheet_name, cell, formula)

工作表管理

• create_worksheet(session_id, sheet_name)
• copy_worksheet(session_id, source_sheet, target_sheet)
• rename_worksheet(session_id, old_name, new_name)
• delete_worksheet(session_id, sheet_name)

格式设置和可视化

• format_range(session_id, sheet_name, start_cell, **formatting_options)
• create_chart(session_id, sheet_name, data_range, chart_type, target_cell)
• create_table(session_id, sheet_name, data_range, table_name=None)

区域操作

• merge_cells(session_id, sheet_name, start_cell, end_cell)
• unmerge_cells(session_id, sheet_name, start_cell, end_cell)
• copy_range(session_id, sheet_name, source_start, source_end, target_start)
• delete_range(session_id, sheet_name, start_cell, end_cell)

架构

基于会话的设计

服务器实现了一个复杂的会话管理系统：

• ExcelSessionManager：采用单例模式管理所有Excel会话。
• 每个会话隔离：每个会话都有独立的Excel应用程序实例。
• 线程安全：每个会话使用RLock防止并发访问问题。
• 资源管理：通过TTL和LRU策略自动清理。
• 错误恢复：全面的错误处理和会话恢复。

性能优化

• 会话重用：消除操作之间重启Excel的开销。
• 连接池：高效的COM对象管理。
• 批量操作：针对同一工作簿的多个操作进行优化。
• 内存管理：主动清理Excel进程。

测试

运行测试

# 运行所有测试
python -m pytest test/

# 运行特定测试类别
python -m pytest test/test_session.py      # 会话管理
python -m pytest test/test_functions.py   # MCP函数测试
python -m pytest test/test_integration.py # 集成测试

测试覆盖率

该项目对以下内容保持100%的测试覆盖率：

• 所有MCP工具函数（测试了17个函数）
• 会话生命周期管理
• 错误处理和恢复
• 性能基准测试

安全考虑

• 文件系统访问：服务器在指定的目录权限内运行。
• Excel进程隔离：每个会话在单独的Excel实例中运行。
• 资源限制：可配置的会话限制防止资源耗尽。
• 输入验证：在调用Excel API之前验证所有输入。
• 安全默认值：提供只读模式，默认使用不可见的Excel实例。

贡献

1. 分叉仓库
2. 创建一个功能分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add amazing feature')
4. 推送到该分支 (git push origin feature/amazing-feature)
5. 打开一个拉取请求

开发设置

git clone https://github.com/yourusername/xlwings-mcp-server.git
cd xlwings-mcp-server
uv venv
uv sync
uv run python -m xlwings_mcp

变更日志

详细的版本历史请参阅 CHANGELOG.md。

故障排除

常见问题

Excel COM错误：确保Excel已正确安装且未在安全模式下运行

# 检查Excel安装情况
excel --version

会话未找到：验证会话未过期（默认TTL：10分钟）

# 列出活动会话
client.call_tool("mcp__xlwings-mcp-server__list_workbooks")

权限被拒绝：使用适当的文件系统权限运行

# Windows：如有需要，以管理员身份运行

调试模式

启用详细日志记录：

export EXCEL_MCP_DEBUG_LOG=1
xlwings-mcp-server

📄 许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

🙏 致谢

• xlwings - 优秀的Python-Excel集成库
• Model Context Protocol - 标准化的AI工具通信协议
• Claude Code - 开发辅助
• 凯瑟琳·约翰逊 - 零错误工程原则的灵感来源

📞 支持

• 问题反馈：GitHub Issues
• 讨论：GitHub Discussions
• 邮箱：haris.musa@outlook.com

为Excel自动化社区用心打造 ❤️