Leave Management MCP Server

休暇管理 MCP サーバー

このリポジトリには、組織の従業員の休暇を管理するための Model Context Protocol（MCP）サーバーが含まれています。このサーバーは、従業員の休暇データを含む Excel ワークブックと連携し、休暇記録を検索・分析するためのツールを提供します。

目次

• 前提条件
• プロジェクト構成
• インストール
• 設定
• サーバーの実行
• トラブルシューティング
• クエリの例

前提条件

• Python 3.9+
• UV パッケージマネージャー
• Claude Desktop（または別の MCP クライアント）
• 休暇データを含む Excel ワークブック

プロジェクト構成

leave-management-mcp/
├── src/
│   ├── __init__.py
│   ├── config.py                # Configuration settings
│   ├── leave_server.py          # Main MCP server
│   ├── data_manager.py          # Data processing module
│   └── models/
│       ├── __init__.py
│       └── employee.py          # Employee data models
├── data/
│   └── leave_tracker.xlsx       # Excel workbook with leave data
├── main.py                      # Entry point wrapper
├── __init__.py                  # Root package marker
├── requirements.txt             # Dependencies
└── README.md                    # Project documentation

インストール

1. このリポジトリをクローンします。

git clone https://github.com/ItsMistahJi/itsmistahji-leave-management-mcp.git
cd leave-management-mcp

2. UV で Python 環境をセットアップします。

pip install uv
uv init .

3. 依存関係をインストールします。

uv add "mcp[cli]" pandas openpyxl python-dotenv PyPDF2

設定

1. プロジェクトのルートに .env ファイルを作成します。

DATA_DIR=/path/to/your/data/directory
EXCEL_FILE=/path/to/your/data/directory/leave_tracker.xlsx
SERVER_NAME=LeaveManagement
DEBUG_MODE=True

2. Excel ワークブックが正しい構成になっていることを確認します。
   • 「Leaves-2025」という名前のシート（または data_manager.py を変更してシート名を指定します）
   • 「Sl No」「Name」「EMP ID」「Location」の列と、月名（「Jan」「Feb」など）の列

サーバーの実行

ローカル開発環境でのテスト

# Test the server locally
uv run python -m src.leave_server

# Install in Claude Desktop for testing
uv run mcp install src/leave_server.py --name "Leave Management"

VS Code との統合

この設定を VS Code の設定に追加します。

"mcpServers": {
  "LeaveManagement": {
    "type": "stdio",
    "command": "uv",
    "args": [
      "run",
      "--with",
      "mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2",
      "mcp",
      "run",
      "/path/to/leave-management-mcp/src/leave_server.py"
    ]
  }
}

[

注： /path/to/leave-management-mcp を実際のプロジェクトパスに置き換えてください。

トラブルシューティング

「No module named 'src'」エラー

このエラーは、Python がモジュール検索パス内で「src」パッケージを見つけられない場合に発生します。

解決方法：

1. __init__.py ファイルを追加して、src を適切なパッケージにします。

touch __init__.py
touch src/__init__.py
touch src/models/__init__.py

2. サーバースクリプト（leave_server.py）を変更して、パスを含めます。

import sys
import os
sys.path.insert(0, os.path.abspath(os.path.dirname(os.path.dirname(__file__))))

3. ルートディレクトリにある main.py ラッパーを使用します。

import sys
import os
sys.path.insert(0, os.path.abspath('.'))
from src.leave_server import mcp
if __name__ == "__main__":
    mcp.run()

「No module named 'pandas'」エラー

このエラーは、サーバーの実行環境に pandas がインストールされていない場合に発生します。

解決方法：

1. すべての依存関係が同じ環境にインストールされていることを確認します。

uv add pandas openpyxl python-dotenv PyPDF2

2. サーバーの実行時に --with フラグを使用します。

uv run --with "mcp[cli],pandas,openpyxl,python-dotenv,PyPDF2" mcp run src/leave_server.py

Excel データの読み込みに関する問題

Excel データで検証エラーが発生する場合は、次の点を確認してください。

1. data_manager.py の load_data 関数を確認し、Excel の構成に合わせて変更します
2. シート名が Excel ファイルと一致していることを確認します
3. 列名を確認し、NaN 値を適切に処理します

クエリの例

サーバーの起動後、Claude に次のように質問できます。

• 「今日、休暇中の人は誰ですか？」
• 「従業員 12345 の休暇残日数を見せてください」
• 「4 月に休暇を取得する従業員をすべて一覧表示してください」
• 「Arun S の休暇の詳細を取得してください」
• 「Jeeva Rao が 3 月に休暇を取得したのはいつですか？」

デバッグ用ログの確認

• Claude Desktop のログ：
  • macOS：~/Library/Logs/Claude/mcp.log
  • Windows：%APPDATA%\Claude\logs\mcp.log
• print 文： サーバーコード内の print() 文の出力はログに表示されます。