macos-tools

The macOS Tools MCP Server provides two main capabilities: system_performance monitoring and enhanced file search. system_performance offers real-time resource metrics (CPU, memory, disk I/O, network), the ability to inspect top resource-consuming processes, historical performance data stored in SQLite, and automated optimization suggestions. enhanced_search enables deep content search across files with support for regex, integrates with macOS Spotlight for fast metadata lookups, and includes tagging via extended attributes to help you organize results. You can invoke each tool with specific actions and optional parameters to tailor results to your needs.

To use these tools, call system_performance with actions such as current, history, processes, or optimize to retrieve immediate metrics, historical trends, or optimization recommendations. Use enhanced_search with actions like search, tag, or untag, and provide parameters such as query, searchType, fileTypes, path, maxResults, and tags to perform precise searches or tagging operations. The tools are designed to work with macOS-native features for speed and accuracy, including Spotlight indexing and extended attributes for tag management.

Prerequisites

• macOS 10.15 or later
• Node.js 18.0.0 or later
• npm or yarn installed

Installation steps

1. Ensure Node.js and npm are available on your system:

ode -v
npm -v

2. Install the MCP server via Claude Desktop configuration or by running the provided npx command:

npx @tgomareli/macos-tools-mcp

3. Configure Claude Desktop (or your preferred MCP client) to point at the server:

• If using Claude Desktop, add the following configuration to your claude_desktop_config.json under mcpServers:

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

4. Alternative installation using mcp-installer:

# Install via mcp-installer (if you prefer a direct install flow)
# Follow the instructions at the MCP Installer project and search for the macos-tools-mcp server

5. After installation, restart Claude Desktop (or your MCP client) to load the macos-tools-mcp server. The available tools should be:

• system_performance
• enhanced_search

Notes and tips:

• The server relies on macOS-native features; ensure you grant necessary permissions for full functionality, especially Full Disk Access for file searches and Developer Tools for process monitoring.
• If you update macOS permissions, you may need to re-run the MCP server to refresh capabilities.
• You can supply additional environment variables via the env object in the mcp_config to customize behavior per environment.
• For large search operations, consider using the maxResults parameter to limit output and avoid overloading the client.
• When running in restricted environments, you may need to adjust Spotlight indexing or file access permissions to improve search performance.