local_mcp

praserocking/local_mcp

3.1

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

A Model Context Protocol (MCP) server designed for macOS developers, providing system monitoring, diagnostics, and utility tools.

🖥️ Local MCP Server

TypeScript Node.js macOS MCP

A Model Context Protocol (MCP) server specifically designed for macOS developers. This server provides comprehensive system monitoring, diagnostics, and utility tools that integrate seamlessly with MCP-compatible clients like Cline.

✨ Key Features

🔧 System Utilities

  • 🛡️ Safe Command Execution: Run shell commands with built-in safety checks to prevent destructive operations
  • 📁 Directory Listing: Browse Downloads, Desktop, and Documents with advanced filtering options
  • 🔍 Smart Filtering: Filter files by age, size, and recursive directory traversal

📊 System Monitoring

  • 💻 System Information: Comprehensive system stats (CPU, memory, uptime, load average)
  • ⚡ Process Monitoring: Real-time process tracking with CPU/memory usage and smart filtering
  • 🌐 Port Scanner: Identify open ports and the processes using them
  • 💾 Disk Usage Analysis: Detailed disk space analysis for development directories
  • 📡 Network Diagnostics: Ping, traceroute, and DNS lookup tools for connectivity testing

🛡️ Safety & Security

  • Dangerous Command Protection: Automatically blocks potentially destructive commands
  • Smart Command Analysis: Warns about commands requiring elevated privileges
  • Comprehensive Safety Patterns: Protects against file system damage, system shutdowns, and security compromises

🚀 Installation & Setup

Prerequisites

  • Node.js (v16 or higher)
  • npm or yarn
  • macOS (optimized for macOS system commands)

Quick Start

  1. Clone and install dependencies:
git clone <repository-url>
cd local_mcp
npm install
  1. Build the project:
npm run build
  1. Run in development mode:
npm run dev
  1. Start production server:
npm start

🔧 Configuration

Adding to MCP Client (e.g., Cline)

Add this server to your MCP configuration file:

{
  "mcpServers": {
    "local-mcp": {
      "command": "node",
      "args": ["/path/to/local_mcp/dist/index.js"],
      "env": {}
    }
  }
}

🎯 What You Can Do with MCP Clients

🧹 "My Downloads folder is a disaster zone"

Ask Cline to help you clean up your Downloads folder. It can find all those year-old files cluttering your Downloads, identify massive files eating your storage, and safely help you delete or organize them. No more manually hunting through hundreds of random downloads!

🚀 "My MacBook sounds like a jet engine"

When your Mac is running hot and loud, ask Cline to identify what's causing the high CPU usage. It can find the top CPU-consuming processes, help you understand what they are, and suggest ways to reduce the load - whether it's killing runaway Chrome tabs or optimizing resource-heavy applications.

🕳️ "Where did all my disk space go?"

Let Cline hunt down your storage-eating directories and files. It can analyze your entire system to find the biggest space hogs, identify forgotten project folders with massive node_modules, and help you reclaim gigabytes of space by cleaning up old build artifacts.

🌐 "Why won't my API connect?"

When your app can't reach an API, Cline can help diagnose the issue. It can test network connectivity, check DNS resolution, trace packet routes to identify where connections are failing, and help you understand if the problem is local or remote.

🔍 "Something's hogging port 3000"

Getting port conflicts when trying to start your development server? Ask Cline to identify what's using your ports. It can find the exact process blocking your port and help you either kill it or move your server to a different port.

📱 "My system feels sluggish during builds"

When your Mac becomes unresponsive during heavy operations like builds or deployments, Cline can monitor your system resources in real-time, identify memory-hungry processes, and suggest optimizations to keep your system responsive.

🏠 "Desktop spring cleaning time"

Let Cline help organize your desktop chaos. It can find old screenshots, identify large files accidentally saved to your desktop, and help you move everything to appropriate folders or archive locations.

🔧 "Is my development environment healthy?"

Before starting a big coding session, ask Cline to run a quick health check. It can verify your system resources are adequate, check if any development servers are already running, and ensure your network connectivity to essential services is working properly.

🗂️ "I need to audit my project files"

Planning to archive old projects? Cline can recursively scan your project directories, identify which ones haven't been touched in months, calculate storage usage, and help you make informed decisions about what to keep or archive.

⚡ "My build process is mysteriously slow"

When builds are taking forever, Cline can help diagnose the bottleneck. It can monitor resource usage during builds, identify if you're running out of memory, check for competing processes, and suggest system optimizations.

🏗️ Project Structure

local_mcp/
├── 📁 src/
│   ├── 📄 index.ts              # Main MCP server class & request handling
│   ├── 📄 tools.ts              # Tool registry and exports
│   ├── 📄 system-monitor.ts     # System monitoring tools & handlers
│   ├── 📄 system-utilities.ts   # Utility tools & safety mechanisms
│   └── 📄 handlers.ts           # Legacy handler implementations
├── 📁 test/                     # Comprehensive test suite
├── 📁 dist/                     # Compiled JavaScript output
├── 📄 package.json              # Dependencies and scripts
├── 📄 tsconfig.json            # TypeScript configuration
├── 📄 jest.config.js           # Test configuration
└── 📄 mcp-config.json          # Sample MCP configuration

🧪 Development & Testing

Available Scripts

# Development
npm run dev          # Run with hot reload using nodemon
npm run build        # Compile TypeScript to JavaScript
npm run start        # Run production build

# Testing
npm test             # Run test suite
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run test:verbose # Run tests with detailed output

# Maintenance
npm run clean        # Remove compiled files
npm run build:full   # Clean and rebuild
npm run verify       # Run tests and build (CI pipeline)

Running Tests

The project includes comprehensive test coverage:

# Run all tests with coverage
npm run test:coverage

# Watch mode for development
npm run test:watch

🛡️ Security Features

Command Safety System

The run_command tool includes sophisticated safety mechanisms:

❌ Blocked Commands (Automatically Prevented)
  • File System Destruction: rm -rf /, dd if=/dev/zero
  • System Control: shutdown, reboot, halt
  • Security Bypass: chmod 777 /, iptables -F
  • Process Disruption: killall -9, kill -9 1
  • Disk Operations: Writing to /dev/sda, mkfs.*
⚠️ Caution Commands (Executed with Warnings)
  • Privilege Escalation: sudo, su
  • File Permissions: chmod, chown
  • File Operations: rm, mv to system directories

Usage Examples

// ✅ Safe command - executes normally
run_command({ command: "ls -la" })

// ⚠️ Caution command - executes with warning
run_command({ command: "sudo npm install -g some-package" })

// ❌ Dangerous command - blocked completely
run_command({ command: "rm -rf /" })
// Returns: "🚨 COMMAND BLOCKED FOR SAFETY 🚨"

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Guidelines

  1. Follow TypeScript best practices
  2. Write tests for new features
  3. Use meaningful commit messages
  4. Update documentation for new tools

Adding New Tools

  1. Define tool schema in appropriate file (system-monitor.ts or system-utilities.ts)
  2. Implement handler method in the same file
  3. Add switch case in src/index.ts
  4. Write comprehensive tests
  5. Update README documentation

🐛 Troubleshooting

Common Issues

Permission Errors
# Ensure proper file permissions
chmod +x dist/index.js
Port Already in Use
# Use port scanner to identify conflicts
port_scanner({ port_range: "3000" })
Memory Issues
# Monitor system resources
system_info({ detailed: true })
process_monitor({ sort_by: "memory", limit: 10 })

📄 License

ISC License - see the file for details.

� Related Projects

Made with ❤️ for macOS developers