Disk Usage MCP Server (Demo)

磁盘使用情况 MCP 服务（演示）

什么是 MCP？

模型上下文协议（MCP）是一种协议，可让 Claude 等 AI 模型与外部工具和服务交互。它允许 Claude 实时访问系统信息，并代表你执行操作。

了解更多关于 MCP 的信息：

• MCP 文档
• MCP Python SDK

你将获得什么

与 Claude Desktop 集成后，这个演示 MCP 服务可让 Claude 实时检查你的 Mac 磁盘使用情况。下面是一个交互示例：

用户：“我目前的磁盘使用情况如何？”

Claude：“我来帮你检查当前的磁盘使用情况。”

[申请使用 disk-usage 工具的权限，用户同意]

{
    "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. 文档字符串解释了每个字段的含义

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 配置目录中创建 claude-config.txt 文件（macOS 上通常为 ~/.config/claude-desktop/），并写入：

{
  "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 配置示例