mac-resource-mcp-server

georgesimbe/mac-resource-mcp-server

3.2

If you are the rightful owner of mac-resource-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Mac Resource Management MCP Server is a comprehensive tool designed to manage and monitor development server instances on macOS, ensuring optimal performance and protection for critical services.

Tools
5
Resources
0
Prompts
0

šŸ› ļø Mac Resource Management MCP Server

A comprehensive Mac Resource Management MCP (Model Context Protocol) server that integrates with both Cursor IDE and Claude Code CLI to prevent port conflicts, manage development server instances, and monitor system resources in real-time with advanced protection for critical services.

āœØ Features

  • šŸ›”ļø Protected Service Detection - Never accidentally kill Docker, databases, or system services
  • šŸŽÆ Project-Aware Management - Track multiple projects and their ports independently
  • šŸ”„ Session Persistence - Survives AI chat restarts and maintains project state
  • šŸš« Port Conflict Prevention - Automatically detect and resolve port conflicts
  • šŸ” Real-time Port Monitoring - Monitor specific ports for changes
  • šŸ’» System Resource Monitoring - CPU, Memory, and Network usage
  • šŸ§  Intelligent Cleanup - Smart development server management that protects critical services
  • šŸ”— Dual Platform Support - Works seamlessly in both Cursor IDE and Claude Code CLI
  • šŸŽ Mac-Optimized - Uses native macOS commands for best performance

šŸš€ Quick Start

Installation

# Clone and install
git clone https://github.com/georgesimbe/mac-resource-mcp-server.git
cd mac-resource-mcp-server
./install.sh

Usage in Cursor IDE & Claude Code CLI

After installation, restart Cursor and Claude Desktop (for Cursor IDE) or ensure Claude Code CLI is properly configured. You can now use natural language:

"Check if port 4321 is available"
"Register my Next.js project on ports 3000 and 3001"
"Kill only development servers, protect my database"
"Show me my active projects"
"Clean up ports for my React project only"
"What services are protected from being killed?"
"Add my custom Redis instance on port 6380 to protected list"

šŸ› ļø Core Tools

Port Management

check_port(port: number)

Check if a specific port is in use and show process details.

Example:

> Check port 3000
šŸ”“ Port 3000 is in use:
  ā€¢ PID: 12345
  ā€¢ Process: node
  ā€¢ Command: npm run dev
kill_port(port: number, force?: boolean)

Kill processes running on a specific port with protection checks.

Protection Features:

  • Automatically protects database servers (MySQL, PostgreSQL, Redis, MongoDB)
  • Prevents killing Docker services
  • Blocks system services (SSH, HTTP, HTTPS)
  • Warns about critical processes before termination
list_dev_ports()

Check status of common development ports (3000, 3001, 4321, 5173, 8000, 8080, 8100, 9000).

monitor_port(port: number, duration?: number)

Monitor a port for changes in real-time.

šŸ›”ļø Protection & Security

list_protected_services()

Show all protected ports and services that cannot be killed.

Example:

šŸ›”ļø Protected Services Configuration:

šŸ“‹ Protected Ports:
  ā€¢ Port 22: SSH
  ā€¢ Port 3306: MySQL
  ā€¢ Port 5432: PostgreSQL
  ā€¢ Port 6379: Redis
  ā€¢ Port 27017: MongoDB
  ā€¢ Port 2375: Docker daemon (unsecured)
  ā€¢ Port 2376: Docker daemon (secured)

šŸ” Currently Running Protected Services:
  ā€¢ MySQL on port 3306 āœ…
  ā€¢ Redis on port 6379 āœ…
add_protected_port(port: number, service: string)

Add custom ports to the protected list.

Example:

> Add port 6380 as "Custom Redis Instance"
šŸ›”ļø Added port 6380 to protected services as "Custom Redis Instance"
kill_dev_servers_selective()

Intelligently kill only development servers while protecting databases and system services.

Smart Detection:

  • Identifies and protects Docker containers
  • Preserves database connections
  • Maintains system services
  • Only terminates development servers

šŸŽÆ Project Management

add_project(name: string, directory: string, ports: number[], framework: string)

Register a project with its ports for session persistence.

Example:

> Register "My Next.js App" at "/Users/dev/my-app" using ports [3000, 3001] with Next.js
āœ… Added project "My Next.js App" with ports [3000, 3001] using Next.js framework
list_active_projects()

List all registered active projects and their ports.

Example:

šŸ“‹ Active Projects:

šŸš€ My Next.js App (Next.js)
   šŸ“ /Users/dev/my-app
   šŸ”Œ Ports: 3000, 3001
   ā° Last active: 12/24/2024, 2:30:15 PM

šŸš€ Astro Blog (Astro)
   šŸ“ /Users/dev/blog
   šŸ”Œ Ports: 4321
   ā° Last active: 12/24/2024, 1:45:22 PM
kill_project_ports(project_name: string)

Kill ports for a specific project only, leaving other projects untouched.

Smart Project Cleanup:

  • Only affects the specified project's ports
  • Protects other projects from accidental termination
  • Maintains database and system service connections
  • Perfect for AI chat restarts

System Monitoring

system_resources()

Get current system resource usage (memory, CPU, network).

kill_dev_servers(server_type?: string)

Kill development servers by type or all.

Server Types:

  • astro - Kill Astro development servers
  • npm - Kill npm development servers
  • vite - Kill Vite servers
  • next - Kill Next.js servers
  • all - Kill all development servers (default)

šŸ”„ Session Persistence

The server automatically maintains session data in ~/.mac-resource-mcp/session.json:

  • Project Registry - Remembers your active projects and their ports
  • Custom Protected Ports - Preserves your custom protection rules
  • Auto-Cleanup - Removes projects inactive for 24+ hours
  • AI Chat Resilience - Survives Claude/Cursor restarts

šŸ§  AI Chat Restart Scenarios

Perfect for when you're running multiple projects and the AI chat restarts:

# Before AI restart - Register your projects
"Register my React app on port 3000 and API on 3001"
"Add my local Redis on port 6380 to protected services"
"Register my Astro blog on port 4321"

# After AI restart - Projects are automatically remembered
"Clean up only my React app ports"  # Only kills 3000, 3001
"Show my active projects"           # Lists all registered projects
"Kill development servers but protect databases"  # Smart cleanup

šŸ”§ Manual Setup

Prerequisites

  • Node.js 18+
  • macOS (optimized for Mac commands)
  • Cursor IDE with Claude integration OR Claude Code CLI

Build from Source

# Install dependencies
npm install

# Build TypeScript
npm run build

# Setup Claude Desktop integration
npm run setup-cursor

Configuration for Different Platforms

Cursor IDE (via Claude Desktop)

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "mac-resource-manager": {
      "command": "node",
      "args": ["/path/to/mac-resource-mcp-server/dist/index.js"]
    }
  }
}
Claude Code CLI

The server works automatically with Claude Code CLI when properly installed. The MCP server will be available through the standard MCP protocol.

For detailed Claude Code CLI configuration, see .

Quick setup for Claude Code CLI:

  1. Automatic: Run ./install.sh - the server will be available automatically
  2. Manual: Add to your project's CLAUDE.md: 
    # MCP Servers
Server path: `/path/to/mac-resource-mcp-server/dist/index.js`
  3. Environment variable: 
    export MAC_RESOURCE_MCP_SERVER="node /path/to/mac-resource-mcp-server/dist/index.js"

šŸ“‹ Shell Aliases

The installation script creates helpful aliases:

# Check development ports
dev-ports

# Kill all development servers
kill-dev

# Clean development environment
dev-clean

# Check specific port
port-check 3000

# Kill specific port
port-kill 3000

šŸ”’ Security & Protection

Built-in Protected Services

  • Databases: MySQL (3306), PostgreSQL (5432), Redis (6379), MongoDB (27017)
  • Docker: Docker daemon (2375, 2376), Docker Swarm (2377)
  • System Services: SSH (22), HTTP (80), HTTPS (443), DNS (53), SMTP (25)
  • Development DBs: SQL Server (1433), CouchDB (5984), Elasticsearch (9200)
  • Message Brokers: RabbitMQ (5672), Kafka (9092)

Smart Process Detection

  • Validates port ranges (1-65535)
  • Prevents killing system-critical processes
  • Graceful termination with SIGTERM by default
  • Process pattern matching for critical services
  • Custom protection rules with session persistence

šŸ› Troubleshooting

Port still in use after killing

Some processes may take time to terminate. Wait a few seconds and check again.

Permission denied errors

Ensure you have proper permissions to kill processes. Some system processes require admin privileges.

Protected service warnings

If you get protection warnings, use list_protected_services to see what's protected and why.

Session data issues

Session data is stored in ~/.mac-resource-mcp/session.json. Delete this file to reset.

šŸ¤ Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Submit a pull request

šŸ“„ License

MIT License - see file for details.

šŸ™ Acknowledgments

  • Built with Model Context Protocol SDK
  • Optimized for macOS system commands
  • Designed for seamless Cursor IDE and Claude Code CLI integration
  • Enhanced with AI-first development workflows

Made with ā¤ļø for the Mac development community