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自動化社區用心打造 ❤️