MacOS Resource Monitor MCP Server

1# MacOS Resource Monitor MCP Server
2[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/Pratyay/mac-monitor-mcp)](https://archestra.ai/mcp-catalog/pratyay__mac-monitor-mcp)
3 
4A Model Context Protocol (MCP) server that identifies resource-intensive processes on macOS across CPU, memory, and network usage.
5 
6## Overview
7 
8MacOS 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.
9 
10## Requirements
11 
12- macOS operating system
13- Python 3.10+
14- MCP server library
15 
16## Installation
17 
18### Option 1: Global Installation (Recommended)
19 
20Install the MCP server globally using uv for system-wide access:
21 
22```bash
23git clone https://github.com/Pratyay/mac-monitor-mcp.git
24cd mac-monitor-mcp
25uv tool install .
26```
27 
28Now you can run the server from anywhere:
29```bash
30mac-monitor
31```
32 
33### Option 2: Development Installation
34 
351. Clone this repository:
36   ```bash
37   git clone https://github.com/Pratyay/mac-monitor-mcp.git
38   cd mac-monitor-mcp
39   ```
40 
412. Create a virtual environment (recommended):
42   ```bash
43   python -m venv venv
44   source venv/bin/activate  
45   ```
46 
473. Install the required dependencies:
48   ```bash
49   pip install mcp
50   ```
51 
52## Usage
53 
54### Global Installation
55If you installed globally with uv:
56```bash
57mac-monitor
58```
59 
60### Development Installation
61If you're running from the project directory:
62```bash
63python src/mac_monitor/monitor.py
64```
65 
66Or using uv run (from project directory):
67```bash
68uv run mac-monitor
69```
70 
71You should see the message:
72```
73Simple MacOS Resource Monitor MCP server starting...
74Monitoring CPU, Memory, and Network resource usage...
75```
76 
77The server will start and expose the MCP endpoint, which can be accessed by an LLM or other client.
78 
79### Available Tools
80 
81The server exposes three tools:
82 
83#### 1. `get_resource_intensive_processes()`
84Returns information about the top 5 most resource-intensive processes in each category (CPU, memory, and network).
85 
86#### 2. `get_processes_by_category(process_type, page=1, page_size=10, sort_by="auto", sort_order="desc")`
87Returns all processes in a specific category with advanced filtering, pagination, and sorting options.
88 
89**Parameters:**
90- `process_type`: `"cpu"`, `"memory"`, or `"network"`
91- `page`: Page number (starting from 1, default: 1)
92- `page_size`: Number of processes per page (default: 10, max: 100)
93- `sort_by`: Sort field - `"auto"` (default metric), `"pid"`, `"command"`, or category-specific fields:
94  - **CPU**: `"cpu_percent"`, `"pid"`, `"command"`
95  - **Memory**: `"memory_percent"`, `"resident_memory_kb"`, `"pid"`, `"command"`
96  - **Network**: `"network_connections"`, `"pid"`, `"command"`
97- `sort_order`: `"desc"` (default) or `"asc"`
98 
99**Example Usage:**
100```python
101# Get first page of CPU processes (default: sorted by CPU% descending)
102get_processes_by_category("cpu")
103 
104# Get memory processes sorted by resident memory, highest first
105get_processes_by_category("memory", sort_by="resident_memory_kb", sort_order="desc")
106 
107# Get network processes sorted by command name A-Z, page 2
108get_processes_by_category("network", page=2, sort_by="command", sort_order="asc")
109 
110# Get 20 CPU processes per page, sorted by PID ascending
111get_processes_by_category("cpu", page_size=20, sort_by="pid", sort_order="asc")
112```
113 
114#### 3. `get_system_overview()`
115Returns 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.
116 
117**Features:**
118 - **CPU Metrics**: Usage percentages, load averages, core count
119 - **Memory Analysis**: Total/used/free memory with percentages
120 - **Disk Statistics**: Storage usage across all filesystems
121 - **Network Overview**: Active connections, interface statistics
122 - **Performance Analysis**: Intelligent bottleneck detection and recommendations
123 - **System Information**: macOS version, uptime, process count
124 
125**Example Usage:**
126```python
127 get_system_overview()  # Get comprehensive system overview
128```
129 
130**Use Cases:** 
131- System performance monitoring and analysis
132- Identifying performance bottlenecks and slowdowns
133- Resource usage trending and capacity planning
134- Troubleshooting system performance issues
135- Getting quick system health overview
136 
137## Sample Output   
138 
139#### `get_resource_intensive_processes()` Output
140 
141```json
142{
143  "cpu_intensive_processes": [
144    {
145      "pid": "1234",
146      "cpu_percent": 45.2,
147      "command": "firefox"
148    },
149    {
150      "pid": "5678",
151      "cpu_percent": 32.1,
152      "command": "Chrome"
153    }
154  ],
155  "memory_intensive_processes": [
156    {
157      "pid": "1234",
158      "memory_percent": 8.5,
159      "resident_memory_kb": 1048576,
160      "command": "firefox"
161    },
162    {
163      "pid": "8901",
164      "memory_percent": 6.2,
165      "resident_memory_kb": 768432,
166      "command": "Docker"
167    }
168  ],
169  "network_intensive_processes": [
170    {
171      "command": "Dropbox",
172      "network_connections": 12
173    },
174    {
175      "command": "Spotify",
176      "network_connections": 8
177    }
178  ]
179}
180```
181 
182#### `get_processes_by_category()` Output
183 
184```json
185{
186  "process_type": "cpu",
187  "processes": [
188    {
189      "pid": "1234",
190      "cpu_percent": 45.2,
191      "command": "firefox"
192    },
193    {
194      "pid": "5678",
195      "cpu_percent": 32.1,
196      "command": "Chrome"
197    }
198  ],
199  "sorting": {
200    "sort_by": "cpu_percent",
201    "sort_order": "desc",
202    "requested_sort_by": "auto"
203  },
204  "pagination": {
205    "current_page": 1,
206    "page_size": 10,
207    "total_processes": 156,
208    "total_pages": 16,
209    "has_next_page": true,
210    "has_previous_page": false
211  }
212}
213```
214 
215## How It Works
216 
217The MacOS Resource Monitor uses built-in macOS command-line utilities:
218 
219- `ps`: To identify top CPU and memory consuming processes
220- `lsof`: To monitor network connections and identify network-intensive processes
221 
222Data is collected when the tool is invoked, providing a real-time snapshot of system resource usage.
223 
224## Integration with LLMs
225 
226This 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.
227 
228## Contributing
229 
230Contributions are welcome! Please feel free to submit a Pull Request.
231 
2321. Fork the repository
2332. Create your feature branch (`git checkout -b feature/amazing-feature`)
2343. Commit your changes (`git commit -m 'Add some amazing feature'`)
2354. Push to the branch (`git push origin feature/amazing-feature`)
2365. Open a Pull Request
237 
238## Management Commands
239 
240If you installed the server globally with uv:
241 
242- **List installed tools:** `uv tool list`
243- **Uninstall:** `uv tool uninstall mac-monitor`
244- **Upgrade:** `uv tool install --force .` (from project directory)
245- **Install from Git:** `uv tool install git+https://github.com/Pratyay/mac-monitor-mcp.git`
246 
247## Recent Updates
248 
249### Version 0.2.0 (Latest)
250- ✅ Added `get_processes_by_category()` tool with pagination and sorting
251- ✅ Added comprehensive sorting options (CPU%, memory, PID, command name)
252- ✅ Added proper Python packaging with `pyproject.toml`
253- ✅ Added global installation support via `uv tool install`
254- ✅ Enhanced error handling and input validation
255- ✅ Added pagination metadata with navigation information
256 
257## Potential Improvements
258 
259Here are some ways you could enhance this monitor:
260 
261- Add disk I/O monitoring
262- Improve network usage monitoring to include bandwidth
263- Add visualization capabilities  
264- Extend compatibility to other operating systems
265- Add process filtering by resource thresholds
266- Add historical data tracking and trends
267