SystemMind 🖥️🧠

A Universal Operating System Management MCP Server for Intelligent System Operations

SystemMind is an MCP (Model Context Protocol) server that provides AI assistants with powerful cross-platform system management capabilities. It enables seamless monitoring, diagnostics, and analysis of operating systems through natural language interactions across Windows, macOS, and Linux.

🎯 What is SystemMind?

SystemMind bridges the gap between AI assistants (like Claude) and operating systems, allowing you to monitor, diagnose, and optimize your computer using conversational interfaces. It's a unified API that works across multiple operating systems, providing real-time insights and diagnostic capabilities.

🔥 Problem It Solves

The Challenge

Modern computer users and administrators often face these issues:

Platform fragmentation: Different commands and tools for Windows, macOS, and Linux
Complex diagnostics: Navigating through multiple system utilities to identify issues
Performance visibility: Difficult to get quick insights into system resource usage
Manual troubleshooting: Time-consuming manual checks for system health and bottlenecks
Context switching: Jumping between Task Manager, Activity Monitor, top, and various CLI tools
Technical barriers: Non-technical users struggle with command-line diagnostics

The Solution

SystemMind provides:

Unified interface across Windows, macOS, and Linux
AI-powered diagnostics through natural language queries
Real-time monitoring with easy-to-parse metrics
Automated performance analysis for troubleshooting system issues
Single entry point for all OS operations
User-friendly output that explains technical concepts simply

🚀 Features

Multi-Platform Support

✅ Windows - Full support for Windows 10/11
✅ macOS - Complete macOS compatibility
✅ Linux - Ubuntu, Debian, RHEL, CentOS, and other distributions
🔄 Auto-detection - Automatically detects OS and adapts accordingly
🔌 Pluggable architecture - Consistent API across all platforms

Comprehensive System Operations

📊 System Information

Complete hardware specifications (CPU, RAM, storage)
Operating system details and architecture
Current resource utilization metrics
System uptime and boot time

🔍 Process Management

List all running processes with resource usage
Identify top memory and CPU consumers
Process categorization (applications, system, browsers, dev tools)
Real-time process monitoring

⚡ Performance Monitoring

CPU usage and core statistics
Memory usage with swap/page file details
Disk I/O statistics and space utilization
Network activity and connection monitoring
Battery status and power management (for laptops)
Temperature monitoring (Linux/macOS)

🔧 Diagnostics & Optimization

Comprehensive performance diagnostics
Startup program analysis and impact assessment
Resource bottleneck identification
Large file discovery for disk cleanup
Security status checks
Health scoring with actionable recommendations

🛠️ Available Tools

Tool	Description	Use Case
`initialize_os_connection`	Detect and initialize OS	Initial setup, platform detection
`get_system_overview`	Complete system specifications	Hardware info, capacity planning
`get_running_processes`	List active processes	Identify resource-heavy apps
`get_performance_summary`	Quick health check	Overall system status assessment
`get_network_info`	Network status and usage	Connectivity troubleshooting
`get_disk_usage`	Storage capacity and I/O	Disk space management
`get_battery_info`	Battery status (laptops)	Power management, battery health
`get_temperature_info`	System temperatures	Overheating detection (Linux/macOS)
`check_startup_programs`	Startup applications list	Boot time optimization
`get_user_info`	Current user and sessions	User management, session info
`find_large_files`	Locate space-consuming files	Disk cleanup, storage optimization
`get_installed_software`	List installed applications	Software inventory
`check_security_status`	Security configuration audit	Antivirus status, security score
`get_system_services`	Running system services	Service management
`get_resource_monitor`	Real-time resource tracking	Live performance monitoring
`diagnose_slow_performance`	Comprehensive diagnostics	Troubleshoot slowness issues
`get_power_settings`	Power management info	Battery optimization, performance modes

💡 How SystemMind Helps

1. Performance Troubleshooting

Scenario: Computer running slowly

You: "My computer is running slow, what's wrong?"
AI: [Uses diagnose_slow_performance + get_running_processes]
"Performance Analysis Complete:
- Chrome is using 3.5 GB RAM across 15 tabs
- CPU usage is normal at 18%
- Memory usage is high at 85%
Root Cause: Memory pressure from browser tabs
Recommendations:
1. Close unused Chrome tabs (will free ~2 GB)
2. Restart Chrome to clear memory leaks
3. Consider adding more RAM if this happens frequently"

2. Resource Optimization

Scenario: Optimizing system startup

You: "My laptop takes forever to start, can you help?"
AI: [Uses check_startup_programs + get_performance_summary]
"Startup Analysis:
- 45 programs launch at startup
- Consuming 2.8 GB RAM before you open anything
- Estimated boot impact: 45-60 seconds
Top startup memory users:
1. Dropbox: 450 MB
2. Spotify: 320 MB
3. Steam: 280 MB
Recommendation: Disable these 3 programs from startup
Potential improvement: 30-40 second faster boot time"

3. Disk Space Management

Scenario: Running out of storage

You: "I'm running out of disk space, what's taking up room?"
AI: [Uses get_disk_usage + find_large_files]
"Storage Analysis:
- Total: 1 TB
- Used: 890 GB (89%) - Almost full!
- Free: 110 GB
Largest files found:
1. VirtualBox VM: 85 GB
2. Old backups: 45 GB
3. Downloaded videos: 23 GB
Quick wins:
- Delete old VM snapshots: ~30 GB
- Remove outdated backups: ~45 GB
- Potential recovery: 75 GB"

4. Security Audit

Scenario: Security health check

You: "Is my computer secure?"
AI: [Uses check_security_status + get_system_overview]
"Security Assessment:
✅ Windows Defender: Active and running
✅ Firewall: Enabled
✅ System Updates: Current (last restart 3 days ago)
⚠️ Windows uptime: 45 days - updates pending
Security Score: 85/100
Recommendations:
1. Restart to apply pending security updates
2. Enable automatic updates
Overall: Your system has good basic security"

5. System Health Monitoring

Scenario: Proactive system check

You: "Give me a health report of my computer"
AI: [Uses get_performance_summary + get_system_overview + get_battery_info]
"System Health Report:
Overall Status: 🟢 EXCELLENT (92/100)
Hardware:
- CPU: 8 cores, 18% usage ✅
- RAM: 16 GB, 42% usage ✅
- Storage: 550 GB free (55%) ✅
- Battery: 85% (charging) ✅
Performance:
- No bottlenecks detected
- All resources within normal range
- System uptime: 2 days
Your computer is running optimally!"

6. Temperature Monitoring (Linux/macOS)

Scenario: Overheating concerns

You: "My laptop feels hot, check the temperatures"
AI: [Uses get_temperature_info + get_resource_monitor]
"Temperature Analysis:
CPU Temperatures:
- Core 0: 78°C ⚠️
- Core 1: 82°C ⚠️
- Core 2: 79°C ⚠️
- Core 3: 81°C ⚠️
Status: Running warm under load
Current Activity:
- CPU usage spiking to 95% during video encoding
Recommendations:
1. Ensure proper ventilation
2. Clean dust from vents
3. Consider laptop cooling pad
4. Check if thermal paste needs replacement (if old laptop)"

7. Network Diagnostics

Scenario: Connectivity issues

You: "My internet seems slow, what's using bandwidth?"
AI: [Uses get_network_info + get_resource_monitor + get_running_processes]
"Network Analysis:
Connection: Wi-Fi @ 866 Mbps
Current Activity (last 5 seconds):
- Download: 4.2 MB/s
- Upload: 850 KB/s
Bandwidth consumers:
1. Steam: Downloading game update
2. OneDrive: Syncing files
3. Chrome: Streaming video
Your connection is fine, but multiple apps are competing
for bandwidth. Pause Steam download for better browsing."

8. Battery Optimization

Scenario: Poor battery life

You: "My battery drains too quickly, help me optimize it"
AI: [Uses get_battery_info + get_power_settings + get_running_processes]
"Battery Optimization Analysis:
Current Status:
- Battery: 45% (3.2 hours remaining)
- Power Mode: High Performance ⚠️
- Screen Brightness: 100% ⚠️
Power-hungry processes:
- Chrome: 15% CPU (multiple tabs)
- Spotify: Playing music
- OneDrive: Syncing
Recommendations:
1. Switch to 'Balanced' power mode (+45 min)
2. Reduce brightness to 60% (+30 min)
3. Close unused Chrome tabs (+20 min)
4. Pause OneDrive sync while on battery (+15 min)
Potential improvement: 1.5 hours extra battery life"

📋 Installation & Setup

Prerequisites

Python 3.8+
Operating System: Windows 10/11, macOS 10.14+, or Linux
Required Python packages: psutil, fastmcp

Install Dependencies

pip install -r requirements.txt

Run the Server

python OS_mcp_server.py

The server starts and is ready for MCP connections.

Configure with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

claude:

{"mcpServers": {
"OS-Mcp": {
"command": "uv",
"args": [
"run",
"--with",
"fastmcp",
"fastmcp",
"run",
"path\\to\\proxy.py" ],
"env": {},
"transport": "stdio"
}
}
}

Continue.dev

name: Sample MCPversion: 0.0.1schema: v1mcpServers:
- name: SystemMind MCP servertype: streamable-httpurl: http://127.0.0.1:9090/mcp/

🔧 Usage Examples

For detailed usage examples, please refer to the example folder.

🏗️ Architecture

┌─────────────────────────────────────────┐
│ AI Assistant (Claude) │
└────────────────┬────────────────────────┘
│ MCP Protocol
┌────────────────▼────────────────────────┐
│ SystemMind Server │
│ ┌─────────────────────────────────┐ │
│ │ Tool Interface Layer │ │
│ │ (17 diagnostic tools) │ │
│ └──────────────┬──────────────────┘ │
│ ┌──────────────▼──────────────────┐ │
│ │ OS Detection & Abstraction │ │
│ └──────────────┬──────────────────┘ │
│ ┌──────────────▼──────────────────┐ │
│ │ Platform-Specific Handlers │ │
│ │ ┌────────┐ ┌──────┐ ┌───────┐ │ │
│ │ │Windows │ │macOS │ │ Linux │ │ │
│ │ └───┬────┘ └──┬───┘ └───┬───┘ │ │
│ └──────┼─────────┼─────────┼─────┘ │
└─────────┼─────────┼─────────┼─────────┘
│ │ │
┌─────▼─────┐ ┌─▼─────┐ ┌─▼──────┐
│ Windows │ │ macOS │ │ Linux │
│ OS │ │ OS │ │ OS │
└───────────┘ └───────┘ └────────┘

🔐 Security Considerations

SystemMind requires standard user-level permissions (no root/admin required for most operations)
Some operations may have limited access on restricted system directories
No authentication layer (relies on MCP transport security)
Does not modify system state (read-only diagnostics)
Exception: clean_temp_files is the only tool that modifies files (disabled by default)
Recommended: Use in trusted environments or add authentication for remote access

🎨 Output Formatting

SystemMind uses emoji-rich, user-friendly formatting:

🟢 Green indicators for healthy status
🟡 Yellow for warnings
🔴 Red for critical issues
✅ Checkmarks for good status
⚠️ Warning symbols for attention items
📊 Charts and visual representations where applicable

🚧 Roadmap

Planned Features

Advanced network diagnostics (port scanning, connection testing)
Automated cleanup suggestions with one-click actions
Historical performance tracking
Export diagnostics reports (PDF/JSON)
Web UI dashboard

Platform-Specific Enhancements

Windows: Registry health checks
macOS: Spotlight indexing status
Linux: systemd service management

🤝 Contributing

Contributions are welcome! Areas for improvement:

Additional platform-specific diagnostics
Enhanced metrics visualization
Performance optimizations
Expanded hardware monitoring
Documentation improvements
Test coverage expansion

How to Contribute

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📊 Comparison: SystemMind vs ContainMind

Feature	SystemMind	ContainMind
Scope	Operating Systems	Containers
Target	System administrators, end users	DevOps, developers
Platforms	Windows, macOS, Linux	Docker, Podman
Use Case	System health, performance	Container orchestration
Complexity	User-friendly, accessible	Technical, developer-focused
Integration	Works together for full-stack monitoring	Works together for full-stack monitoring

Better Together: Use SystemMind to monitor your host system and ContainMind to monitor containers running on it!

🐛 Troubleshooting

Common Issues

Tool returns "Please run 'initialize_os_connection' first"

Solution: Always call initialize_os_connection() before using other tools

"No result received from client-side tool execution"

Cause: Tool timeout or permission error
Solution: Check permissions, try with smaller scope (e.g., limit in find_large_files)

Temperature monitoring not available (Windows)

This is expected - Windows doesn't expose temperature sensors through standard APIs
Use third-party tools like HWMonitor for Windows temperature monitoring

Permission errors when scanning files

Normal for system directories - tool will skip inaccessible files
Check the "permission errors" count in output

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

Built with:

FastMCP - MCP server framework
psutil - Cross-platform system utilities
Anthropic Claude - AI assistant integration

Special thanks to the open-source community for the excellent tools and libraries.

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Wiki

🌟 Star History

If you find SystemMind helpful, please consider giving it a star ⭐ on GitHub!

SystemMind - Making system management conversational, intelligent, and accessible to everyone. 🚀

💼 The Mind Suite

SystemMind is part of the Mind Suite - a collection of intelligent management tools:

🐋 ContainMind - Universal container management
🖥️ SystemMind - Operating system intelligence (this project)

From containers to OS - Mind everything. 🧠

Name		Name	Last commit message	Last commit date
assets		assets
clients/claude		clients/claude
example		example
scripts		scripts
.gitignore		.gitignore
LICENSE		LICENSE
OS_mcp_server.py		OS_mcp_server.py
Readme.md		Readme.md
requirements.txt		requirements.txt

Latest commit

History

Folders and files

Repository files navigation