Macos Tools MCP Server

🚀 macOS 內部工具 MCP 服務器

這是一個適用於 macOS 的 MCP 服務器，提供高級系統監控和文件搜索功能。

🚀 快速開始

本 MCP 服務器專為 macOS 設計，提供系統性能監控和文件搜索等高級功能。下面將詳細介紹其功能、安裝步驟、使用方法等內容。

✨ 主要特性

系統性能監控

• 實時監控：跟蹤 CPU、內存、磁盤 I/O 和網絡統計信息。
• 進程分析：查看資源消耗最多的進程，並提供詳細指標。
• 歷史跟蹤：使用 SQLite 存儲和分析一段時間內的性能數據。
• 優化建議：獲得智能建議，以提升系統性能。

增強型文件搜索

• 深度內容搜索：使用正則表達式或純文本在文件內容中進行搜索。
• Spotlight 集成：藉助 macOS Spotlight 進行快速元數據搜索。
• 標籤管理：使用擴展屬性創建、搜索和管理自定義文件標籤。
• 高級功能：支持模糊匹配、布爾運算符和文件類型過濾。

📦 安裝指南

要求

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

權限

為實現完整功能，服務器需要特定權限：

1. 完全磁盤訪問權限（建議用於文件搜索）：
   • 系統偏好設置 → 安全性與隱私 → 隱私 → 完全磁盤訪問權限
   • 添加終端
2. 開發者工具（用於進程監控）：
   • 若未安裝 Xcode 命令行工具，請執行以下命令：

xcode-select --install

安裝步驟

Claude 桌面配置

若要在 Claude 桌面中使用此 MCP 服務器，請按以下步驟操作：

1. 打開 Claude 桌面配置文件：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json
2. 將 macOS 工具服務器添加到配置中：

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

3. 若已配置其他 MCP 服務器，請將 macOS 工具配置添加到現有的 mcpServers 對象中：

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

4. 保存配置文件並重啟 Claude 桌面。
5. 此時，你應能在 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
});

🔧 技術細節

關鍵特性

1. 原生 macOS 集成
   • 使用原生命令（ps、mdfind、xattr）以實現最佳性能
   • 利用 Spotlight 索引進行快速搜索
   • 支持 macOS 擴展屬性進行標籤管理
2. 性能優化
   • 多級緩存系統
   • 防抖操作
   • 系統調用速率限制
   • 大文件流式處理
3. 數據持久化
   • 使用 SQLite 數據庫存儲性能歷史數據
   • 可配置數據保留策略
   • 高效的時間序列查詢

📄 許可證

本項目採用 MIT 許可證，詳情請參閱 LICENSE 文件。

測試服務器

在 Claude 桌面中配置好服務器後，可使用以下提示測試所有功能：

快速測試提示

1. 基本性能檢查：

Show me my current system performance metrics

2. 進程分析：

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

3. 文件搜索：

Search for TODO comments in JavaScript files in my current directory

4. 系統優化：

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 集成以進行文件版本搜索