JinDaGe - macos-tools-mcp-server MCP Details

article

README

🚀 macOS 内部工具 MCP 服务器

这是一个适用于 macOS 的 MCP 服务器，提供高级系统监控和文件搜索功能。

🚀 快速开始

本 MCP 服务器专为 macOS 设计，提供系统性能监控和文件搜索等高级功能。下面将详细介绍其功能、安装步骤、使用方法等内容。

✨ 主要特性

系统性能监控

实时监控：跟踪 CPU、内存、磁盘 I/O 和网络统计信息。
进程分析：查看资源消耗最多的进程，并提供详细指标。
历史跟踪：使用 SQLite 存储和分析一段时间内的性能数据。
优化建议：获得智能建议，以提升系统性能。

增强型文件搜索

深度内容搜索：使用正则表达式或纯文本在文件内容中进行搜索。
Spotlight 集成：借助 macOS Spotlight 进行快速元数据搜索。
标签管理：使用扩展属性创建、搜索和管理自定义文件标签。
高级功能：支持模糊匹配、布尔运算符和文件类型过滤。

📦 安装指南

要求

macOS 10.15 或更高版本
Node.js 18.0.0 或更高版本
npm 或 yarn 包管理器

权限

为实现完整功能，服务器需要特定权限：

完全磁盘访问权限（建议用于文件搜索）：
- 系统偏好设置 → 安全性与隐私 → 隐私 → 完全磁盘访问权限
- 添加终端
开发者工具（用于进程监控）：
- 若未安装 Xcode 命令行工具，请执行以下命令：

xcode-select --install

安装步骤

Claude 桌面配置

若要在 Claude 桌面中使用此 MCP 服务器，请按以下步骤操作：

打开 Claude 桌面配置文件：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- Linux：~/.config/Claude/claude_desktop_config.json
将 macOS 工具服务器添加到配置中：

{
  "mcpServers": {
    "macos-tools": {
      "command": "npx",
      "args": [
        "@tgomareli/macos-tools-mcp"
      ],
      "env": {}
    }
  }
}

若已配置其他 MCP 服务器，请将 macOS 工具配置添加到现有的 mcpServers 对象中：

{
  "mcpServers": {
    "existing-server": {
      // ... 现有配置
    },
    "macos-tools": {
      "command": "npx",
      "args": [
        "@tgomareli/macos-tools-mcp"
      ],
      "env": {}
    }
  }
}

保存配置文件并重启 Claude 桌面。
此时，你应能在 Claude 桌面中看到 macOS 工具服务器，包含两个工具：
- system_performance - 监控系统资源
- enhanced_search - 高级文件搜索和标签管理

MCP 安装程序

你也可以使用 mcp-installer 直接安装，无需手动打开配置文件。在 Claude 中输入以下命令：

Hey Claude, install the MCP server named macos-tools-mcp

💻 使用示例

系统性能监控工具

// 获取当前系统性能指标
await callTool("system_performance", {
  action: "current",
  metric: "all"
});

// 获取过去 24 小时的内存使用历史
await callTool("system_performance", {
  action: "history",
  timeRange: "24h",
  metric: "memory"
});

// 获取占用 CPU 最多的进程
await callTool("system_performance", {
  action: "processes",
  metric: "cpu"
});

// 分析系统并提供性能优化建议
await callTool("system_performance", {
  action: "optimize"
});

增强型文件搜索工具

// 在当前目录的 JavaScript 文件中搜索 TODO 注释
await callTool("enhanced_search", {
  action: "search",
  query: "TODO|FIXME",
  searchType: "regex",
  fileTypes: ["js", "ts", "py"],
  path: "~/Projects"
});

// 为文件添加标签
await callTool("enhanced_search", {
  action: "tag",
  path: "~/Documents/important.pdf",
  tags: ["urgent", "project-x"]
});

// 搜索带有特定标签的文件
await callTool("enhanced_search", {
  action: "search",
  searchType: "tags",
  tags: ["urgent"],
  path: "~/Documents"
});

// 在配置文件中搜索包含特定单词的文件
await callTool("enhanced_search", {
  action: "search",
  query: "apiKey",
  searchType: "content",
  fileTypes: ["json", "env"],
  path: "~/Projects",
  maxResults: 50
});

🔧 技术细节

关键特性

原生 macOS 集成
- 使用原生命令（ps、mdfind、xattr）以实现最佳性能
- 利用 Spotlight 索引进行快速搜索
- 支持 macOS 扩展属性进行标签管理
性能优化
- 多级缓存系统
- 防抖操作
- 系统调用速率限制
- 大文件流式处理
数据持久化
- 使用 SQLite 数据库存储性能历史数据
- 可配置数据保留策略
- 高效的时间序列查询

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

测试服务器

在 Claude 桌面中配置好服务器后，可使用以下提示测试所有功能：

快速测试提示

基本性能检查：

Show me my current system performance metrics

进程分析：

What are the top 5 CPU-consuming processes on my system?

文件搜索：

Search for TODO comments in JavaScript files in my current directory

系统优化：

Analyze my system and suggest performance optimizations

综合测试套件

使用以下综合提示测试所有功能：

I want to test the macOS Tools MCP server. Please help me:

1. **系统性能测试**：
    - 显示当前系统性能指标（CPU、内存、磁盘、网络）
    - 显示占用 CPU 最多的前 5 个进程
    - 显示过去一小时的内存使用历史
    - 分析系统并提供优化建议
    - 获取占用内存最多的进程

2. **文件搜索测试**：
    - 在主目录中搜索包含 "TODO" 或 "FIXME" 注释的所有 JavaScript 和 TypeScript 文件
    - 在当前项目目录中查找文件名包含 "test" 的所有文件
    - 在配置文件（.json、.env、.yml）中搜索包含 "password" 一词的文件
    - 使用正则表达式在文本文件中查找所有电子邮件地址
    - 搜索过去 24 小时内修改过的文件

3. **标签管理测试**：
    - 为文件 /Users/tornikegomareli/Development/macos-tools-mcp/README.md 添加 "important" 和 "reviewed" 标签
    - 搜索所有带有 "important" 标签的文件
    - 从 README 文件中移除 "reviewed" 标签
    - 为 src 目录中的所有 TypeScript 文件添加 "source-code" 标签

4. **组合操作**：
    - 在执行大文件搜索时监控系统性能
    - 查找资源密集型进程，然后搜索其日志文件
    - 显示当前磁盘使用情况，并搜索大文件（> 100MB）

5. **边界情况**：
    - 在不存在的目录中搜索
    - 尝试为没有修改权限的文件添加标签
    - 请求无效时间范围的性能数据
    - 使用无效的正则表达式进行搜索

预期行为

性能监控：应返回实时指标、进程列表、历史数据和优化建议
文件搜索：应能按内容、文件名或标签查找文件，支持正则表达式
标签管理：应能成功添加/移除标签并按标签搜索
错误处理：应能优雅处理权限错误、无效路径和格式错误的查询

未来增强功能

[ ] 支持 GPU 监控
[ ] 网络连接分析
[ ] 应用程序特定性能跟踪
[ ] 与 Time Machine 集成以进行文件版本搜索

macos-tools-mcp-server