# System Control MCP Server

A Model Context Protocol (MCP) server built with Python and the official [Model Context Protocol SDK](https://github.com/modelcontextprotocol/python-sdk).

This server equips LLMs (in Claude Desktop, Cursor, LibreChat, or any MCP client) with system monitoring, process inspection, filesystem analytics, and CLI command execution capabilities.

---

## Features & Tools

### System & Diagnostics
- **`get_system_info`**: Inspect OS, kernel, machine architecture, CPU core counts, hostname, and system uptime.
- **`get_resource_usage`**: Real-time snapshot of CPU usage (overall & per core), RAM memory (used, free, percent), swap, and disk partition stats.

### Process Management
- **`list_processes`**: List running processes sorted by memory or CPU usage, with optional name filtering and limit.
- **`get_process_details`**: Detailed view for a specific PID (command line, memory RSS, threads, start time, cwd).
- **`kill_process`**: Gracefully terminate (SIGTERM) or forcibly kill (SIGKILL) a process by PID (with safety guards).

### CLI Automation & Environment
- **`execute_command`**: Execute PowerShell (Windows) or Bash (Linux/macOS) commands with working directory and timeout control, capturing stdout, stderr, and exit codes.
- **`get_environment_variable`**: Inspect specific environment variables or list variable names (masks sensitive tokens/keys).
- **`get_directory_summary`**: Summarize contents, item counts, and file sizes for any directory.

### Resources & Prompts
- **Resource `system://health`**: Markdown live snapshot of system resource usage.
- **Prompt `system_health_audit`**: Ready-to-use prompt template instructing LLMs to audit system health and detect bottlenecks.

---

## Setup & Installation

### 1. Prerequisites
- Python 3.10+

### 2. Clone and Setup Environment
```bash
git clone https://github.com/<your-username>/system-mcp-server.git
cd system-mcp-server

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\Activate.ps1
# On macOS/Linux:
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
```

---

## Connecting to MCP Clients

### Claude Desktop (`claude_desktop_config.json`)

Open your Claude Desktop configuration file:
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the server configuration under `mcpServers`:

```json
{
  "mcpServers": {
    "system-control": {
      "command": "/absolute/path/to/system-mcp-server/.venv/bin/python",
      "args": [
        "/absolute/path/to/system-mcp-server/server.py"
      ]
    }
  }
}
```
*(On Windows, replace `/absolute/path/to/` with your directory path and use `Scripts\\python.exe`)*

### Cursor / VS Code / Other MCP Clients

Use standard stdio transport:
- **Command**: `/path/to/system-mcp-server/.venv/bin/python` (or `.venv\Scripts\python.exe` on Windows)
- **Args**: `["/path/to/system-mcp-server/server.py"]`

---

## Testing

### Run Unit Tests
```bash
python test_server.py
```

### Interactive Testing with MCP Inspector
You can test the server interactively in your browser using the official MCP Inspector:
```bash
npx @modelcontextprotocol/inspector python server.py
```

---

## License

MIT License. See [LICENSE](LICENSE) for details.