Skip to main content
Glama
Sign In

macOS Tools MCP Server

by tornikegomareli
GitHub
TypeScript
MIT License
  • Apple
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

macOS Tools MCP Server

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

Table of Contents

Features

System Performance Monitor

  • 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

Installation

Prerequisites

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

Setup

  1. Clone the repository:
git clone https://github.com/yourusername/macos-tools-mcp.git cd macos-tools-mcp
  1. Install dependencies:
npm install
  1. Build the project:
npm run build
  1. Make the script executable:
chmod +x dist/index.js

Permissions

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 or your IDE
  2. Developer Tools (for process monitoring):
    • Install Xcode Command Line Tools if not already installed:
    xcode-select --install

Usage

Starting the Server

Run the MCP server:

npm start

Or use it directly:

node dist/index.js

Claude Desktop Configuration

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration:

  1. First, ensure the project is built:
cd /Users/tornikegomareli/Development/macos-tools-mcp npm install npm run build
  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": "node", "args": [ "/Users/tornikegomareli/Development/macos-tools-mcp/dist/index.js" ], "env": {} } } }

Note: Replace /Users/tornikegomareli/Development/macos-tools-mcp with the actual path where you cloned this repository.

  1. 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": "node", "args": [ "/Users/tornikegomareli/Development/macos-tools-mcp/dist/index.js" ], "env": {} } } }
  1. Save the configuration file and restart Claude Desktop.
  2. 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

Available Tools

system_performance

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

Architecture

Project Structure

macos-tools-mcp/ ├── src/ │ ├── index.ts # MCP server entry point │ ├── tools/ │ │ ├── performance-monitor.ts │ │ ├── spotlight-enhanced.ts │ │ └── types.ts │ └── utils/ │ ├── system-info.ts # macOS system calls │ ├── file-search.ts # File search utilities │ └── cache.ts # Performance caching ├── dist/ # Compiled JavaScript ├── package.json ├── tsconfig.json └── README.md

Key Features

  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

Troubleshooting

Common Issues

  1. Permission Denied Errors
    • Ensure the terminal has Full Disk Access
    • Some operations may require sudo (temperature monitoring)
  2. Spotlight Not Finding Files
    • Check if Spotlight indexing is enabled
    • Verify the search path is not excluded from Spotlight
  3. High CPU Usage
    • Adjust cache TTL values in cache.ts
    • Limit search depth and file types
    • Use more specific search queries

Debug Mode

Enable debug logging by setting the environment variable:

DEBUG=macos-tools-mcp node dist/index.js

Security Considerations

  • All shell commands are properly escaped to prevent injection
  • File paths are validated and normalized
  • Sensitive directories can be excluded via configuration
  • Rate limiting prevents resource exhaustion

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

  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

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

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

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

Provides advanced system monitoring and file search capabilities for macOS, allowing users to track performance metrics and perform enhanced file searches with content analysis and tagging features.

  1. Table of Contents
    1. Features
      1. System Performance Monitor
      2. Enhanced File Search
    2. Installation
      1. Prerequisites
      2. Setup
      3. Permissions
    3. Usage
      1. Starting the Server
      2. Claude Desktop Configuration
    4. Available Tools
      1. system_performance
      2. enhanced_search
    5. Architecture
      1. Project Structure
      2. Key Features
    6. Troubleshooting
      1. Common Issues
      2. Debug Mode
    7. Security Considerations
      1. License
        1. Testing the Server
          1. Quick Test Prompts
          2. Comprehensive Test Suite
          3. Expected Behaviors
        2. Future Enhancements

          Related MCP Servers

          • mcp-everything-search

            mamertofabian
            -
            security
            A
            license
            -
            quality
            This server provides: * Fast file search capabilities using Everything SDK * Windows-specific implementation * Complements existing filesystem servers with specialized search functionality
            Last updated -
            57
            Python
            MIT License

          • Everything Search MCP Server

            Alihkhawaher
            A
            security
            F
            license
            A
            quality
            Provides integration with Everything Search Engine allowing powerful file search capabilities through the Model Context Protocol with advanced search options like regex, case sensitivity, and sorting.
            Last updated -
            1
            3
            JavaScript

          • System Resource Monitor MCP Server

            abhinav7895
            -
            security
            A
            license
            -
            quality
            Provides Claude with real-time system monitoring capabilities, including CPU, memory, disk, network, battery, and internet speed metrics.
            Last updated -
            TypeScript
            MIT License
            • Apple

          • Everything Search MCP Server

            aripo99
            -
            security
            -
            license
            -
            quality
            Provides fast file searching capabilities across Windows, macOS, and Linux operating systems using platform-specific search technologies.
            Last updated -
            Python
            MIT License

          View all related MCP servers

          New MCP Servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/tornikegomareli/macos-tools-mcp-server'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server