Disk Usage

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

什么是MCP？

模型上下文协议（MCP）是一种协议，它使像Claude这样的AI模型能够与外部工具和服务进行交互。它允许Claude访问实时系统信息并代表您执行操作。

了解有关MCP的更多信息：

• MCP文件
• MCP Python SDK

所得

当与Claude Desktop集成时，此演示MCP服务器使Claude能够实时检查您的磁盘使用情况（在Mac上）。以下是一个交互示例：


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

克劳德：“让我帮你查一下你当前的磁盘使用情况。”

\[批准使用磁盘使用工具，用户同意\]

View result from ``get_disk_usage` from `disk-usage`` (local)

{
    "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%\ 安装点：/系统/体积/数据\ 设备：/dev/disk3s5

您的磁盘当前容量为87%，还有27.0GB的可用空间。如果你担心高使用率，你可能想考虑清理一些文件以释放更多空间。"

运作原理

服务器功能

当服务器启动时，它通过MCP协议向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
    """

这个告诉克劳德：

1. 服务器提供了一个名为 get_disk_usage
2. 该工具返回一个包含详细磁盘信息的字典
3. docstring解释了每个字段的含义

完整的Claude MCP交互流程

1. 克劳德的初始系统提示:

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  XML block:

get_disk_usage
Explain why you need disk usage information

1. 用户查询:

User: What is my current disk usage?

1. Claude的工具选择响应:

I'll check your disk usage information.

get_disk_usage
User has requested current disk usage information. This tool will provide detailed statistics about disk space utilization.

1. 克劳德桌面应用程序→ MCP服务器:

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

1. MCP服务器→ 克劳德桌面应用程序:

{
    "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
}

1. 向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.

1. 克劳德的最终回应:

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"}
        }
      }
    }
  ]
}

1. 用户查询:

   User: "What is my current disk usage?"

1. 克劳德的工具选择:

Claude认识到此查询需要磁盘信息，并决定使用 get_disk_usage 工具。

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

1. 工具调用和响应:

   // 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%"
   }

1. 克劳德的自然反应:

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
   }

1. 工具广告:

服务器以其功能进行响应，包括 get_disk_usage 工具及其模式。

1. 工具调用:

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

1. 服务器响应:

   // 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上的磁盘3s5）
3. 服务器解析输出并返回结构化数据，包括：

- 总磁盘空间 - 已用空间 - 可用空间 - 预留空间（系统预留的空间） - 使用百分比 - 安装点和设备信息

需求

• macOS（此工具专为Mac的磁盘结构而设计）
• Python 3.11+
• pip（Python包管理器）

运行服务器

1. 克隆此存储库

1. 安装依赖项：

pip install -r requirements.txt

1. 运行服务器：

python disk_usage_server.py

备注：此服务器专门查找 /System/Volumes/Data macOS上的分区（disk3s5）。它不适用于其他操作系统。

Claude桌面集成

1. 创建一个 claude-config.txt Claude Desktop配置目录中的文件（通常 ~/.config/claude-desktop/ 在macOS上），使用：

{
  "mcpServers": {
    "disk-usage": {
      "command": "python3",
      "args": [
        "
/disk_usage_server.py"
      ]
    }
  }
}

1. 替换 `

` 保存服务器文件的实际路径

1. 重新启动克劳德桌面

学习成果

该项目展示了：

1. 如何使用Python创建一个简单的MCP服务器
2. 如何将系统命令集成到MCP工具中
3. 如何为AI消费构建数据结构
4. 如何处理系统特定的细节（如磁盘分区）
5. 如何提供清晰、易读的技术数据摘要

文件

• disk_usage_server.py：主MCP服务器实现
• requirements.txt：Python依赖关系
• claude-config.txt：克劳德桌面配置示例