macOS工具MCP服务器

Name: macOS工具MCP服务器
Author: tornikegomareli

作者：tornikegomareli15 星标更新：2025-08-03

安装使用来源：spider==github.com

项目介绍

macOS 内部工具 MCP 服务器

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

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

安装

需求

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

权限

为了实现全部功能，服务器需要某些权限：

完全磁盘访问（推荐用于文件搜索）：
- 系统偏好设置 → 安全与隐私 → 隐私 → 完全磁盘访问
- 添加终端
开发者工具（用于进程监控）：
- 如果尚未安装，请安装 Xcode 命令行工具：
```
xcode-select --install
```

如何安装

Claude 桌面配置

要使用此 MCP 服务器与 Claude 桌面：

打开您的 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-tools 配置添加到现有的 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, 安装名为 macos-tools-mcp 的 MCP 服务器

可用工具

system_performance

监控和分析系统性能指标。

参数：

action (必需): "current" | "history" | "processes" | "optimize"
timeRange (可选): 历史数据的时间范围 ("1h", "24h", "7d")
metric (可选): 要分析的具体指标 ("cpu", "memory", "disk", "network", "all")

示例：

await callTool("system_performance", {
  action: "current",
  metric: "all"
});

await callTool("system_performance", {
  action: "history",
  timeRange: "24h",
  metric: "memory"
});

await callTool("system_performance", {
  action: "processes",
  metric: "cpu"
});

await callTool("system_performance", {
  action: "optimize"
});

enhanced_search

具有内容分析和标记能力的高级文件搜索。

参数：

action (必需): "search" | "tag" | "untag"
query (可选): 搜索查询（支持正则表达式）
searchType (可选): "content" | "filename" | "tags" | "regex"
fileTypes (可选): 要包含的文件扩展名数组
path (可选): 搜索的根目录
maxResults (可选): 结果的最大数量
tags (可选): 要搜索或应用的标签数组

示例：

// 在代码文件中搜索 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 桌面中配置了服务器，您可以使用这些提示来测试所有功能：

快速测试提示

基本性能检查：
```
显示我当前的系统性能指标
```

进程分析：

我系统中消耗 CPU 最多的前 5 个进程是什么？

文件搜索：

在我的当前目录中搜索 JavaScript 文件中的 TODO 注释

系统优化：

分析我的系统并提出性能优化建议

全面测试套件

使用这个全面提示来测试所有功能：

我想测试 macOS 工具 MCP 服务器。请帮助我：

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

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

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

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

5. **边缘案例**：
   - 在不存在的目录中搜索
   - 尝试标记我没有权限修改的文件
   - 请求无效时间段的性能数据
   - 使用无效的正则表达式模式搜索

预期行为

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

未来改进

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