A MCP server for macOS that provides advanced system monitoring and file search capabilities.
Table of Contents
- 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
Enhanced File Search
- 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
Installation
Requirements
- macOS 10.15 or later
- Node.js 18.0.0 or later
- npm or yarn package manager
Permissions
For full functionality, the server requires certain permissions:
- Full Disk Access (recommended for file search):
- System Preferences → Security & Privacy → Privacy → Full Disk Access
- Add Terminal
- Developer Tools (for process monitoring):
- Install Xcode Command Line Tools if not already installed:
How to install
Claude Desktop Configuration
To use this MCP server with Claude Desktop:
- 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
- Add the macOS Tools server to your configuration:
{
"mcpServers": {
"macos-tools": {
"command": "npx",
"args": [
"@tgomareli/macos-tools-mcp"
],
"env": {}
}
}
}
- 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": {}
}
}
}
- Save the configuration file and restart Claude Desktop.
- You should now see the macOS Tools server available in Claude Desktop with two tools:
system_performance - Monitor system resourcesenhanced_search - Advanced file search and tagging
MCP Installer
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"
});
enhanced_search
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 includepath (optional): Root directory for searchmaxResults (optional): Maximum number of resultstags (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
});
Key Features
- Native macOS Integration
- Uses native commands (ps, mdfind, xattr) for optimal performance
- Leverages Spotlight index for fast searches
- Supports macOS extended attributes for tagging
- Performance Optimization
- Multi-level caching system
- Debounced operations
- Rate limiting for system calls
- Streaming for large files
- Data Persistence
- SQLite database for performance history
- Configurable data retention
- Efficient time-series queries
License
MIT License - see LICENSE file for details
Testing the Server
Once you've configured the server in Claude Desktop, you can use these prompts to test all functionality:
Quick Test Prompts
- Basic Performance Check:
Show me my current system performance metrics
- Process Analysis:
What are the top 5 CPU-consuming processes on my system?
- File Search:
Search for TODO comments in JavaScript files in my current directory
- System Optimization:
Analyze my system and suggest performance optimizations
Comprehensive Test Suite
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
Expected Behaviors
- 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
Future Enhancements