MMPC — Monitor My PC

Lightweight, cross-platform device monitoring with Discord as the dashboard.

MMPC watches a computer or server you own or are authorized to monitor, reports live system stats to Discord, keeps a single status message continuously updated, and forwards alerts from tools like CrystalDiskInfo through a secure webhook receiver.

---

✨ Overview

MMPC (Monitor My PC) turns Discord into a live dashboard for a device you're authorized to monitor. Instead of spamming a channel with new messages, MMPC keeps one status embed and edits it on an interval — CPU, memory, storage, network, and hardware detail, all in one place — while a centralized alert manager watches thresholds, service health, SSH activity, and inbound webhooks from other tools.

┌────────────────────┐
│  Monitored Device   │
│                      │
│  psutil / platform   │
│  SMART / sensors      │
│  systemd / services   │
└─────────┬────────────┘
          │
          ▼
┌────────────────────┐        ┌────────────────────┐
│   MMPC Agent         │◄──────│  CrystalDiskInfo /   │
│                      │ HTTP  │  external monitoring │
│  Collectors + Alert  │webhook│  tools                │
│  Manager + Webhook    │       └────────────────────┘
│  Server              │
└─────────┬────────────┘
          │ Bot messages / webhooks
          ▼
┌────────────────────┐
│      Discord         │
│                      │
│  Status • Alerts •    │
│  SSH • CrystalDisk    │
└────────────────────┘

🚀 Features

• 🖥️ Persistent Status Message — One embed, edited on a configurable interval, instead of channel spam.
• 📊 Deep System Monitoring — CPU, memory, disks (with SMART where available), network throughput, GPU, sensors, top processes.
• 🧩 Hardware Inventory — Motherboard, BIOS, battery, USB/PCI devices where the OS exposes them, with graceful Unavailable fallbacks.
• 🔐 SSH Log Monitoring — Tails auth.log/secure or journalctl for logins, failures, and invalid-user attempts.
• 💽 CrystalDiskInfo Webhook — Dedicated endpoint that turns drive health alerts into clean embeds.
• 🌐 Generic Webhook Receiver — Bring your own monitoring tool; map any JSON payload to a Discord channel.
• 🚨 Centralized Alert Manager — Severity levels, cooldowns, deduplication, rate limiting, and recovery notifications.
• 🤖 Slash Commands — /status, /info, /hardware, /disks, /network, /processes, /services, /uptime, /alerts, /reload, restricted to configured administrators.
• 📬 Bot or Webhook Delivery — Choose per channel whether alerts go through the bot, a Discord webhook, or both.
• 🩺 Self-Health Tracking — The agent tracks its own uptime, resource usage, and alert delivery success.
• 🧱 Capability-Based Design — Every collector returns available / data / error; nothing crashes because a sensor is missing.
• 🔒 Privacy-First Defaults — Public IP lookups and MAC address exposure are opt-in, never on by default.

---

📦 Requirements

• Python 3.12+
• A Discord bot application and token
• A Discord server (guild) where the bot has been invited
• Windows, Linux, or macOS (feature availability varies by platform — see below)

---

🛠️ Installation

1. Clone the repository

git clone https://github.com/exoworo/mmpc.git
cd mmpc

2. Run the installer for your platform

Windows (PowerShell):

.\scripts\install_windows.ps1

Linux (Debian/Ubuntu):

chmod +x scripts/install_linux.sh
./scripts/install_linux.sh

macOS:

chmod +x scripts/install_macos.sh
./scripts/install_macos.sh

Each installer creates a virtual environment, installs dependencies, and copies config/config.example.yml → config/config.yml and .env.example → .env if they don't already exist.

3. Configure

Edit config/config.yml and .env — see Configuration below.

4. Run

./.venv/bin/python -m app.main       # Linux/macOS
.\.venv\Scripts\python.exe -m app.main   # Windows

On first run without a configuration file, MMPC prints setup instructions instead of starting with insecure defaults.

---

🤖 Discord Bot Setup

1. Create an application at the Discord Developer Portal.
2. Add a Bot to the application and copy its token into DISCORD_BOT_TOKEN in .env.
3. Under Privileged Gateway Intents, none of the privileged intents are required — MMPC only uses default intents.
4. Invite the bot to your server with the applications.commands and bot scopes.

Required Discord Permissions

Keep permissions minimal — avoid Administrator entirely:

Permission	Why
View Channels	Read the channels it posts to
Send Messages	Post status and alert embeds
Embed Links	Render rich embeds
Read Message History	Locate/edit the persistent status message
Edit Messages	Update the status embed in place

---

📡 Channel Configuration

Every channel is independently configurable in config.yml:

discord:
  channels:
    status: "123456789012345678"
    alerts: "123456789012345678"
    ssh: "123456789012345678"
    crystal_disk: "123456789012345678"
    system_info: "123456789012345678"
    logs: "123456789012345678"

For each alert channel, choose how delivery happens:

discord:
  channel_delivery:
    alerts: "bot"      # "bot", "webhook", or "both"
    ssh: "bot"
    crystal_disk: "both"

discord_webhooks:
  alerts: "${DISCORD_ALERT_WEBHOOK}"
  ssh: "${DISCORD_SSH_WEBHOOK}"
  crystal_disk: "${DISCORD_CRYSTALDISK_WEBHOOK}"

---

⚙️ Configuration

MMPC is configured through config/config.yml, with secrets pulled from environment variables (.env or the process environment) using ${VAR_NAME} syntax. Never hard-code credentials into the YAML file.

Environment Variables

Variable	Description
DISCORD_BOT_TOKEN	Discord bot token
DISCORD_ALERT_WEBHOOK / DISCORD_SSH_WEBHOOK / DISCORD_CRYSTALDISK_WEBHOOK	Optional Discord webhook URLs
CRYSTALDISK_WEBHOOK_SECRET	Shared secret for the CrystalDiskInfo endpoint
MONITORING_WEBHOOK_SECRET / BACKUP_WEBHOOK_SECRET	Example secrets for generic external webhooks

Key Sections

monitoring:
  update_interval: 30   # seconds between status message edits

privacy:
  show_private_ips: true
  show_public_ip: false      # public IP lookups are disabled by default
  show_mac_addresses: false  # MAC addresses are hidden by default

thresholds:
  cpu_usage: 95
  memory_usage: 90
  disk_usage: 90
  cpu_temperature: 85

alerts:
  cooldown: 300          # seconds before an identical alert can re-fire
  deduplicate: true
  recovery_notifications: true

See config/config.example.yml for the full annotated reference.

---

🔐 SSH Monitoring Setup

ssh_monitoring:
  enabled: true
  log_sources:
    - /var/log/auth.log
    - /var/log/secure
  alert_successful_logins: true
  alert_failed_logins: true
  channel: ssh

MMPC tails whichever configured log path exists on the host. If none exist and journalctl is available, it falls back to journalctl -f -u ssh -u sshd. MMPC never logs, stores, or transmits passwords or private keys — only the event metadata (user, source address, method, timestamp).

---

💽 CrystalDiskInfo Webhook Setup

1. Enable the endpoint in config.yml:

   crystal_disk:
     enabled: true
     endpoint: "/webhook/crystaldisk"
     channel: crystal_disk
   

2. Set CRYSTALDISK_WEBHOOK_SECRET in .env.

3. Configure CrystalDiskInfo (or a forwarding script) to POST JSON to http://127.0.0.1:8787/webhook/crystaldisk with header:

   X-Webhook-Secret: your_secret_here
   

---

🌐 Generic Webhook Setup

Add as many external integrations as you need:

external_webhooks:
  - name: "Monitoring Server"
    path: "/webhook/monitoring"
    secret: "${MONITORING_WEBHOOK_SECRET}"
    discord_channel: alerts

The webhook server binds to 127.0.0.1 by default and is disabled unless webhooks.enabled: true is set — it is never exposed to the internet automatically. Put it behind a reverse proxy with TLS if remote tools need to reach it.

---

🏃 Running Manually

./.venv/bin/python -m app.main

🧰 Running as a Service

Linux (systemd): the installer registers mmpc.service under a dedicated, non-root mmpc user with automatic restarts. Manage it with:

sudo systemctl enable --now mmpc.service
sudo systemctl status mmpc.service
journalctl -u mmpc.service -f

Windows: the installer explains how to register MMPC with NSSM using a transparent, documented command — MMPC does not modify Windows services on its own.

macOS: the installer prints a ready-to-use launchd .plist template and the launchctl load / unload commands to run MMPC automatically.

---

🔄 Updating

git pull
./.venv/bin/pip install -r requirements.txt --upgrade
sudo systemctl restart mmpc.service   # if running as a systemd service

---

🐛 Troubleshooting

Bot never comes online

Check DISCORD_BOT_TOKEN in .env and confirm the bot was actually invited to the guild referenced by discord.guild_id.

Status message never appears

• Confirm discord.channels.status is a valid channel ID.
• Confirm the bot has View Channels, Send Messages, and Edit Messages in that channel.
• Check logs/monitor.log for delivery errors.

401 Unauthorized from a webhook

The X-Webhook-Secret header didn't match the configured secret for that endpoint.

429 Rate limit exceeded

The webhook receiver enforces a per-source request rate limit; slow down the sender or adjust the source's retry interval.

Sensor/hardware fields show "Unavailable"

Expected on many systems — sensor and hardware exposure varies significantly by OS, firmware, and installed tooling (e.g. smartctl, nvidia-smi, lm-sensors). MMPC reports Unavailable instead of crashing or guessing.

---

🛡️ Security Considerations

• Secrets are only ever read from environment variables — nothing is hard-coded.
• Every webhook endpoint requires a matching X-Webhook-Secret; unauthenticated requests are rejected with 401.
• The webhook server and optional local web interface bind to 127.0.0.1 by default and are never exposed to the internet automatically.
• Slash commands are restricted to the Discord user IDs listed in discord.administrators.
• Logs redact tokens, webhook URLs, secrets, passwords, and private keys before they ever hit disk.
• MMPC does not collect credentials, browser data, keystrokes, or any private data unrelated to system administration, and performs no covert or stealth operations — it identifies itself clearly wherever it runs.
• Process monitoring intentionally excludes command-line arguments by default since they can contain secrets.

---

🗑️ Uninstallation

sudo systemctl disable --now mmpc.service   # if installed as a service
sudo rm /etc/systemd/system/mmpc.service
sudo systemctl daemon-reload

Then remove the project directory (including config/config.yml, .env, and data/mmpc.sqlite3, which hold your configuration and local alert-state database).

---

🏗️ Project Structure

MMPC/
├── app/
│   ├── main.py
│   ├── config.py
│   ├── logging.py
│   ├── health.py
│   ├── identity.py
│   ├── storage.py
│   ├── webserver.py
│   │
│   ├── discord/
│   │   ├── bot.py
│   │   ├── messages.py
│   │   └── webhooks.py
│   │
│   ├── monitoring/
│   │   ├── system.py
│   │   ├── cpu.py
│   │   ├── memory.py
│   │   ├── disks.py
│   │   ├── network.py
│   │   ├── processes.py
│   │   ├── temperatures.py
│   │   ├── gpu.py
│   │   ├── services.py
│   │   └── hardware.py
│   │
│   ├── alerts/
│   │   ├── manager.py
│   │   ├── ssh.py
│   │   ├── crystal_disk.py
│   │   └── webhook.py
│   │
│   └── platform/
│       ├── windows.py
│       ├── linux.py
│       └── macos.py
│
├── config/
│   └── config.example.yml
├── scripts/
│   ├── install_windows.ps1
│   ├── install_linux.sh
│   └── install_macos.sh
├── systemd/
│   └── mmpc.service
├── tests/
├── requirements.txt
├── .env.example
├── README.md
└── LICENSE

---

📄 License

MMPC is licensed under the MIT License.

MIT License

Copyright (c) 2026 Exoworo

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

---

MMPC — Monitor My PC
Device monitoring, delivered directly to Discord.

Made with ❤️ by Exoworo