Xlwings MCP Server

🚀 xlwings-mcp-server

xlwingsを使用したExcel自動化のための堅牢なモデルコンテキストプロトコル（MCP）サーバーです。このサーバーは、セッションベースのアーキテクチャを通じて、包括的な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 OS（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

📚 ドキュメント

セッション管理

• 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 - 開発支援
• Katherine Johnson - ゼロエラーエンジニアリング原則の啓発者

📞 サポート

• 問題報告：GitHub Issues
• ディスカッション：GitHub Discussions
• メール：haris.musa@outlook.com

Excel自動化コミュニティのために❤️ で作られました