Content
# MacOS Resource Monitor MCP Server
A Model Context Protocol (MCP) server that identifies resource-intensive processes on macOS across CPU, memory, and network usage.
## Overview
MacOS Resource Monitor is a lightweight MCP server that exposes an MCP endpoint for monitoring system resources. It analyzes CPU, memory, and network usage, and identifies the most resource-intensive processes on your Mac, returning data in a structured JSON format.
## Requirements
- macOS operating system
- Python 3.10+
- MCP server library
## Installation
### Option 1: Global Installation (Recommended)
Install the MCP server globally using uv for system-wide access:
```bash
git clone https://github.com/Pratyay/mac-monitor-mcp.git
cd mac-monitor-mcp
uv tool install .
```
Now you can run the server from anywhere:
```bash
mac-monitor
```
### Option 2: Development Installation
1. Clone this repository:
```bash
git clone https://github.com/Pratyay/mac-monitor-mcp.git
cd mac-monitor-mcp
```
2. Create a virtual environment (recommended):
```bash
python -m venv venv
source venv/bin/activate
```
3. Install the required dependencies:
```bash
pip install mcp
```
## Usage
### Global Installation
If you installed globally with uv:
```bash
mac-monitor
```
### Development Installation
If you're running from the project directory:
```bash
python src/mac_monitor/monitor.py
```
Or using uv run (from project directory):
```bash
uv run mac-monitor
```
You should see the message:
```
Simple MacOS Resource Monitor MCP server starting...
Monitoring CPU, Memory, and Network resource usage...
```
The server will start and expose the MCP endpoint, which can be accessed by an LLM or other client.
### Available Tools
The server exposes three tools:
#### 1. `get_resource_intensive_processes()`
Returns information about the top 5 most resource-intensive processes in each category (CPU, memory, and network).
#### 2. `get_processes_by_category(process_type, page=1, page_size=10, sort_by="auto", sort_order="desc")`
Returns all processes in a specific category with advanced filtering, pagination, and sorting options.
**Parameters:**
- `process_type`: `"cpu"`, `"memory"`, or `"network"`
- `page`: Page number (starting from 1, default: 1)
- `page_size`: Number of processes per page (default: 10, max: 100)
- `sort_by`: Sort field - `"auto"` (default metric), `"pid"`, `"command"`, or category-specific fields:
- **CPU**: `"cpu_percent"`, `"pid"`, `"command"`
- **Memory**: `"memory_percent"`, `"resident_memory_kb"`, `"pid"`, `"command"`
- **Network**: `"network_connections"`, `"pid"`, `"command"`
- `sort_order`: `"desc"` (default) or `"asc"`
**Example Usage:**
```python
# Get first page of CPU processes (default: sorted by CPU% descending)
get_processes_by_category("cpu")
# Get memory processes sorted by resident memory, highest first
get_processes_by_category("memory", sort_by="resident_memory_kb", sort_order="desc")
# Get network processes sorted by command name A-Z, page 2
get_processes_by_category("network", page=2, sort_by="command", sort_order="asc")
# Get 20 CPU processes per page, sorted by PID ascending
get_processes_by_category("cpu", page_size=20, sort_by="pid", sort_order="asc")
```
#### 3. `get_system_overview()`
Returns comprehensive system overview with aggregate statistics similar to Activity Monitor. Provides CPU, memory, disk, network statistics, and intelligent performance analysis to help identify bottlenecks and optimization opportunities.
**Features:**
- **CPU Metrics**: Usage percentages, load averages, core count
- **Memory Analysis**: Total/used/free memory with percentages
- **Disk Statistics**: Storage usage across all filesystems
- **Network Overview**: Active connections, interface statistics
- **Performance Analysis**: Intelligent bottleneck detection and recommendations
- **System Information**: macOS version, uptime, process count
**Example Usage:**
```python
get_system_overview() # Get comprehensive system overview
```
**Use Cases:**
- System performance monitoring and analysis
- Identifying performance bottlenecks and slowdowns
- Resource usage trending and capacity planning
- Troubleshooting system performance issues
- Getting quick system health overview
## Sample Output
#### `get_resource_intensive_processes()` Output
```json
{
"cpu_intensive_processes": [
{
"pid": "1234",
"cpu_percent": 45.2,
"command": "firefox"
},
{
"pid": "5678",
"cpu_percent": 32.1,
"command": "Chrome"
}
],
"memory_intensive_processes": [
{
"pid": "1234",
"memory_percent": 8.5,
"resident_memory_kb": 1048576,
"command": "firefox"
},
{
"pid": "8901",
"memory_percent": 6.2,
"resident_memory_kb": 768432,
"command": "Docker"
}
],
"network_intensive_processes": [
{
"command": "Dropbox",
"network_connections": 12
},
{
"command": "Spotify",
"network_connections": 8
}
]
}
```
#### `get_processes_by_category()` Output
```json
{
"process_type": "cpu",
"processes": [
{
"pid": "1234",
"cpu_percent": 45.2,
"command": "firefox"
},
{
"pid": "5678",
"cpu_percent": 32.1,
"command": "Chrome"
}
],
"sorting": {
"sort_by": "cpu_percent",
"sort_order": "desc",
"requested_sort_by": "auto"
},
"pagination": {
"current_page": 1,
"page_size": 10,
"total_processes": 156,
"total_pages": 16,
"has_next_page": true,
"has_previous_page": false
}
}
```
## How It Works
The MacOS Resource Monitor uses built-in macOS command-line utilities:
- `ps`: To identify top CPU and memory consuming processes
- `lsof`: To monitor network connections and identify network-intensive processes
Data is collected when the tool is invoked, providing a real-time snapshot of system resource usage.
## Integration with LLMs
This MCP server is designed to work with Large Language Models (LLMs) that support the Model Context Protocol. The LLM can use the `get_resource_intensive_processes` tool to access system resource information and provide intelligent analysis.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
## Management Commands
If you installed the server globally with uv:
- **List installed tools:** `uv tool list`
- **Uninstall:** `uv tool uninstall mac-monitor`
- **Upgrade:** `uv tool install --force .` (from project directory)
- **Install from Git:** `uv tool install git+https://github.com/Pratyay/mac-monitor-mcp.git`
## Recent Updates
### Version 0.2.0 (Latest)
- ✅ Added `get_processes_by_category()` tool with pagination and sorting
- ✅ Added comprehensive sorting options (CPU%, memory, PID, command name)
- ✅ Added proper Python packaging with `pyproject.toml`
- ✅ Added global installation support via `uv tool install`
- ✅ Enhanced error handling and input validation
- ✅ Added pagination metadata with navigation information
## Potential Improvements
Here are some ways you could enhance this monitor:
- Add disk I/O monitoring
- Improve network usage monitoring to include bandwidth
- Add visualization capabilities
- Extend compatibility to other operating systems
- Add process filtering by resource thresholds
- Add historical data tracking and trends
You Might Also Like
MarkItDown MCP
markitdown-mcp is a lightweight MCP server for converting various URIs to Markdown.
Github
GitHub MCP Server connects AI tools to GitHub for code management and automation.

apisix
Apache APISIX is an API Gateway for managing APIs and microservices.
opik
Opik is a powerful tool for managing and optimizing machine learning experiments.

MCP Toolbox for Databases
MCP Toolbox for Databases is an open-source server simplifying database tool...

sqlglot
SQLGlot is a no-dependency SQL parser and transpiler supporting 30 dialects.