Disk Usage MCP Server (Demo)

ディスク使用量 MCP サーバー（デモ）

MCP とは？

Model Context Protocol（MCP）は、Claude などの AI モデルが外部のツールやサービスとやり取りできるようにするプロトコルです。Claude がシステムのリアルタイム情報にアクセスし、ユーザーに代わって操作を実行できるようにします。

MCP の詳細はこちらをご覧ください。

• MCP ドキュメント
• MCP Python SDK

利用できる機能

Claude Desktop と連携すると、このデモ MCP サーバーによって、Claude は Mac のディスク使用量をリアルタイムで確認できます。やり取りの例を示します。

ユーザー：「現在のディスク使用量を教えてください」

Claude：「現在のディスク使用量を確認します。」

[ディスク使用量ツールの使用許可を求め、ユーザーが同意]

{
    "device": "/dev/disk3s5",
    "total_gb": "228.0GB",
    "used_gb": "177.0GB",
    "available_gb": "27.0GB",
    "reserved_gb": "24.0GB",
    "percent_used": "87%",
    "mount": "/System/Volumes/Data",
    "summary": "Total: 228.0GB | Used: 177.0GB | Available: 27.0GB | Reserved: 24.0GB | Usage: 87%"
}

Claude：「現在のディスク使用量は次のとおりです。

ディスク容量の合計：228.0GB
使用済み容量：177.0GB
利用可能な容量：27.0GB
予約済み容量：24.0GB
使用率：87%
マウントポイント：/System/Volumes/Data
デバイス：/dev/disk3s5

現在、ディスクの容量の 87% を使用しており、27.0GB の空き容量があります。使用量が多いことが気になる場合は、ファイルを整理して空き容量を増やすことを検討してみてください。」

仕組み

サーバーの機能

サーバーは起動時に、MCP プロトコルを通じて Claude に自身の機能を通知します。Claude に表示される内容は次のとおりです。

@mcp.tool()
def get_disk_usage() -> Dict[str, str]:
    """Get current disk usage information for the system disk
    
    Returns:
        A dictionary containing disk usage information with fields:
        - device: Device name
        - total_gb: Total size in GB
        - used_gb: Used space in GB
        - available_gb: Available space in GB
        - reserved_gb: Space reserved by system in GB
        - percent_used: Usage percentage
        - mount: Mount point
        - summary: Human-readable summary of disk usage
    """

これにより、Claude は次のことを認識します。

1. サーバーが get_disk_usage というツールを提供している
2. ツールがディスクの詳細情報を含む辞書を返す
3. docstring で各フィールドの意味を説明している

Claude と MCP の完全なやり取りの流れ

1. Claude への初期システムプロンプト：

You are Claude, an AI assistant. You have access to these tools:

get_disk_usage() -> Dict[str, str]
    "Get current disk usage information for the system disk"

To use this tool, respond with a <tool_call> XML block:
<tool_call>
<name>get_disk_usage</name>
<reason>Explain why you need disk usage information</reason>
</tool_call>

2. ユーザーからの質問：

User: What is my current disk usage?

3. Claude によるツール選択の応答：

I'll check your disk usage information.

<tool_call>
<name>get_disk_usage</name>
<reason>User has requested current disk usage information. This tool will provide detailed statistics about disk space utilization.</reason>
</tool_call>

4. Claude Desktop アプリ → MCP サーバー：

// HTTP POST to MCP Server
{
    "jsonrpc": "2.0",
    "method": "invoke",
    "params": {
        "tool": "get_disk_usage",
        "args": {}
    },
    "id": 1
}

5. MCP サーバー → Claude Desktop アプリ：

{
    "jsonrpc": "2.0",
    "result": {
        "device": "/dev/disk3s5",
        "total_gb": "228.0GB",
        "used_gb": "177.0GB",
        "available_gb": "27.0GB",
        "reserved_gb": "24.0GB",
        "percent_used": "87%",
        "mount": "/System/Volumes/Data",
        "summary": "Total: 228.0GB | Used: 177.0GB | Available: 27.0GB | Reserved: 24.0GB | Usage: 87%"
    },
    "id": 1
}

6. Claude への新しいリクエスト（ツールの出力をコンテキストとして含む）：

User: What is my current disk usage?

Tool Response:
{
    "device": "/dev/disk3s5",
    "total_gb": "228.0GB",
    "used_gb": "177.0GB",
    "available_gb": "27.0GB",
    "reserved_gb": "24.0GB",
    "percent_used": "87%",
    "mount": "/System/Volumes/Data",
    "summary": "Total: 228.0GB | Used: 177.0GB | Available: 27.0GB | Reserved: 24.0GB | Usage: 87%"
}

Provide a helpful response to the user based on this disk usage information.

7. Claude の最終応答：

Here's your current disk usage information:

Total Disk Space: 228.0GB   
Used Space: 177.0GB   
Available Space: 27.0GB   
Reserved Space: 24.0GB   
Usage Percentage: 87%   
Mount Point: /System/Volumes/Data   
Device: /dev/disk3s5

Your disk is currently at 87% capacity, with 27.0GB of space still available. If you're concerned about the high usage, you might want to consider cleaning up some files to free up more space.

完全な流れは次のとおりです。

1. Claude は利用可能なツールを認識した状態で開始します
2. ユーザーが質問します
3. Claude はディスク情報が必要だと判断し、ツールの使用を提案します
4. 許可を得ると、ツールの応答が会話に挿入されます
5. Claude は生データを処理し、役立つ回答を生成します

技術的な実装

# Tool advertisement from server
{
  "tools": [
    {
      "name": "get_disk_usage",
      "description": "Get current disk usage information for the system disk",
      "parameters": {},  # No parameters needed
      "returns": {
        "type": "object",
        "properties": {
          "device": {"type": "string"},
          "total_gb": {"type": "string"},
          "used_gb": {"type": "string"},
          "available_gb": {"type": "string"},
          "reserved_gb": {"type": "string"},
          "percent_used": {"type": "string"},
          "mount": {"type": "string"},
          "summary": {"type": "string"}
        }
      }
    }
  ]
}

2. ユーザーからの質問：

   User: "What is my current disk usage?"
   

3. Claude によるツールの選択： Claude は、この質問にディスク情報が必要だと判断し、get_disk_usage ツールを使用します。

   Claude: "Let me check your current disk usage for you."
   [approval to use disk-usage tool, user gives consent]
   

4. ツールの呼び出しと応答：

   // Raw tool response
   {
     "device": "/dev/disk3s5",
     "total_gb": "228.0GB",
     "used_gb": "177.0GB",
     "available_gb": "27.0GB",
     "reserved_gb": "24.0GB",
     "percent_used": "87%",
     "mount": "/System/Volumes/Data",
     "summary": "Total: 228.0GB | Used: 177.0GB | Available: 27.0GB | Reserved: 24.0GB | Usage: 87%"
   }
   

5. Claude による自然な応答： Claude は生データを処理し、人にわかりやすい回答を提供します。

   Here's your current disk usage information:
   
   Total Disk Space: 228.0GB   
   Used Space: 177.0GB   
   Available Space: 27.0GB   
   Reserved Space: 24.0GB   
   Usage Percentage: 87%   
   Mount Point: /System/Volumes/Data   
   Device: /dev/disk3s5
   
   Your disk is currently at 87% capacity, with 27.0GB of space still available. If you're concerned about the high usage, you might want to consider cleaning up some files to free up more space."
   

通信プロトコル

内部では、MCP は WebSocket 上で双方向の JSON-RPC プロトコルを使用します。仕組みは次のとおりです。

1. 初期化：

   // Claude -> Server
   {
     "jsonrpc": "2.0",
     "method": "initialize",
     "params": {
       "protocolVersion": "2024-11-05",
       "capabilities": {},
       "clientInfo": {
         "name": "claude-ai",
         "version": "0.1.0"
       }
     },
     "id": 0
   }
   

2. ツールの通知： サーバーは、get_disk_usage ツールとそのスキーマを含む自身の機能を応答として返します。

3. ツールの呼び出し：

   // Claude -> Server
   {
     "jsonrpc": "2.0",
     "method": "invoke",
     "params": {
       "tool": "get_disk_usage",
       "args": {}
     },
     "id": 1
   }
   

4. サーバーの応答：

   // Server -> Claude
   {
     "jsonrpc": "2.0",
     "result": {
       "device": "/dev/disk3s5",
       "total_gb": "228.0GB",
       "used_gb": "177.0GB",
       ...
     },
     "id": 1
   }
   

この WebSocket ベースのプロトコルにより、次のことが可能になります。

• 接続の維持
• 双方向の通信
• 構造化された型情報
• ツールの検出とドキュメントの参照

実装

1. MCP サーバー（disk_usage_server.py）は、Python の subprocess モジュールを使って df コマンドを実行します
2. /System/Volumes/Data パーティション（macOS の disk3s5）を対象にします
3. サーバーは出力を解析し、次の情報を含む構造化データを返します。
   • ディスク容量の合計
   • 使用済み容量
   • 利用可能な容量
   • 予約済み容量（システムが予約している容量）
   • 使用率
   • マウントポイントとデバイスの情報

要件

• macOS（このツールは Mac のディスク構造専用に設計されています）
• Python 3.11+
• pip（Python パッケージマネージャー）

サーバーの実行

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

2. 依存関係をインストールします：

pip install -r requirements.txt

3. サーバーを実行します：

python disk_usage_server.py

注：このサーバーは、macOS の /System/Volumes/Data パーティション（disk3s5）を特定して動作します。他のオペレーティングシステムでは動作しません。

Claude Desktop との連携

1. Claude Desktop の設定ディレクトリ（macOS では通常 ~/.config/claude-desktop/）に claude-config.txt ファイルを作成し、次の内容を記述します：

{
  "mcpServers": {
    "disk-usage": {
      "command": "python3",
      "args": [
        "<path-to-your-directory>/disk_usage_server.py"
      ]
    }
  }
}

2. <path-to-your-directory> を、サーバーのファイルを保存した実際のパスに置き換えます

3. Claude Desktop を再起動します

学習内容

このプロジェクトでは、次の方法を紹介します：

1. Python を使ってシンプルな MCP サーバーを作成する方法
2. システムコマンドを MCP ツールに組み込む方法
3. AI が利用するデータを構成する方法
4. システム固有の情報（ディスクパーティションなど）を扱う方法
5. 技術データを明確で人が読みやすい要約として提供する方法

ファイル

• disk_usage_server.py：MCP サーバーの主要な実装
• requirements.txt：Python の依存関係
• claude-config.txt：Claude Desktop の設定例