A MCP server for macOS that provides advanced system monitoring and file search capabilities.

• System Performance Monitor
• Enhanced File Search
• Installation
  • Requirements
  • Permissions
• How to install
  • Claude Desktop Configuration
  • MCP Installer
• Available Tools
  • system_performance
  • enhanced_search
  • Key Features
• License
• Testing the Server
  • Quick Test Prompts
  • Comprehensive Test Suite
  • Expected Behaviors
• Future Enhancements

• Real-time Monitoring: Track CPU, memory, disk I/O, and network statistics
• Process Analysis: View top resource-consuming processes with detailed metrics
• Historical Tracking: Store and analyze performance data over time using SQLite
• Optimization Suggestions: Get intelligent recommendations to improve system performance

• Deep Content Search: Search within file contents using regex or plain text
• Spotlight Integration: Leverage macOS Spotlight for fast metadata searches
• Tag Management: Create, search, and manage custom file tags using extended attributes
• Advanced Features: Fuzzy matching, boolean operators, and file type filtering

• macOS 10.15 or later
• Node.js 18.0.0 or later
• npm or yarn package manager

For full functionality, the server requires certain permissions:

1. Full Disk Access (recommended for file search):

   • System Preferences → Security & Privacy → Privacy → Full Disk Access
   • Add Terminal

2. Developer Tools (for process monitoring):

   • Install Xcode Command Line Tools if not already installed:

   xcode-select --install

To use this MCP server with Claude Desktop:

1. Open your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the macOS Tools server to your configuration:

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

3. If you already have other MCP servers configured, add the macos-tools configuration to the existing mcpServers object:

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

4. Save the configuration file and restart Claude Desktop.

5. You should now see the macOS Tools server available in Claude Desktop with two tools:

   • system_performance - Monitor system resources
   • enhanced_search - Advanced file search and tagging

Or you can use mcp-installer for installing it directly, without opening config files.

Just type in claude

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

Monitor and analyze system performance metrics.

Parameters:

• action (required): "current" | "history" | "processes" | "optimize"
• timeRange (optional): Time range for historical data ("1h", "24h", "7d")
• metric (optional): Specific metric to analyze ("cpu", "memory", "disk", "network", "all")

Examples:

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" });

Advanced file search with content analysis and tagging capabilities.

Parameters:

• action (required): "search" | "tag" | "untag"
• query (optional): Search query (supports regex)
• searchType (optional): "content" | "filename" | "tags" | "regex"
• fileTypes (optional): Array of file extensions to include
• path (optional): Root directory for search
• maxResults (optional): Maximum number of results
• tags (optional): Array of tags to search for or apply

Examples:

// Search for TODO comments in code files 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. Native macOS Integration

   • Uses native commands (ps, mdfind, xattr) for optimal performance
   • Leverages Spotlight index for fast searches
   • Supports macOS extended attributes for tagging

2. Performance Optimization

   • Multi-level caching system
   • Debounced operations
   • Rate limiting for system calls
   • Streaming for large files

3. Data Persistence

   • SQLite database for performance history
   • Configurable data retention
   • Efficient time-series queries

MIT License - see LICENSE file for details

Once you've configured the server in Claude Desktop, you can use these prompts to test all functionality:

1. Basic Performance Check:

   Show me my current system performance metrics 

2. Process Analysis:

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

3. File Search:

   Search for TODO comments in JavaScript files in my current directory 

4. System Optimization:

   Analyze my system and suggest performance optimizations 

Use this comprehensive prompt to test all features:

I want to test the macOS Tools MCP server. Please help me: 1. **System Performance Testing**: - Show me the current system performance metrics (CPU, memory, disk, network) - Display the top 5 processes consuming the most CPU - Show me memory usage history for the last hour - Analyze my system and provide optimization suggestions - Get the top memory-consuming processes 2. **File Search Testing**: - Search for all JavaScript and TypeScript files containing "TODO" or "FIXME" comments in my home directory - Find all files with "test" in their filename in the current project directory - Search for files containing the word "password" in configuration files (.json, .env, .yml) - Use regex to find all email addresses in text files - Search for files modified in the last 24 hours 3. **Tag Management Testing**: - Tag this file with "important" and "reviewed": /Users/tornikegomareli/Development/macos-tools-mcp/README.md - Search for all files tagged with "important" - Remove the "reviewed" tag from the README file - Tag all TypeScript files in the src directory with "source-code" 4. **Combined Operations**: - Monitor system performance while performing a large file search - Find resource-intensive processes and then search for their log files - Show current disk usage and search for large files (> 100MB) 5. **Edge Cases**: - Search in a non-existent directory - Try to tag a file I don't have permission to modify - Request performance data for an invalid time range - Search with an invalid regex pattern 

• Performance Monitor: Should return real-time metrics, process lists, historical data, and optimization suggestions
• File Search: Should find files by content, name, or tags, with support for regex patterns
• Tag Operations: Should successfully add/remove tags and search by them
• Error Handling: Should gracefully handle permission errors, invalid paths, and malformed queries

• GPU monitoring support
• Network connection analysis
• Application-specific performance tracking
• Integration with Time Machine for file version search