README.md•4.09 kB
# System Information MCP Server
A modular FastMCP server providing focused system diagnostic tools for efficient troubleshooting and environment analysis. Each tool targets specific system aspects for optimal performance and clarity.
## 🚀 Features
### 📊 Modular Tool Design
- **10 specialized tools** for targeted diagnostics
- **Efficient data collection** with minimal overhead
- **Raw text output** for optimal performance
- **Cross-platform compatibility** (macOS, Linux, Windows)
### 🔧 Available Tools
| Tool | Purpose | Key Information |
|------|---------|----------------|
| `get_system_summary` | Quick system overview | Hostname, OS, CPU, RAM, uptime |
| `get_hardware_details` | Comprehensive hardware specs | CPU cores, memory, GPU detection |
| `get_display_info` | Display/monitor analysis | Resolution, refresh rate, HDR status |
| `get_network_status` | Network diagnostics | Interfaces, IPs, DNS, VPN detection |
| `get_storage_analysis` | Storage overview | Disk usage, partitions, filesystem types |
| `get_connected_devices` | Peripheral inventory | USB and Bluetooth devices |
| `get_user_environment` | Session context | User info, timezone, locale settings |
| `get_running_processes` | Process analysis | Top processes by CPU/memory usage |
| `get_open_ports` | Network security | Listening ports and services |
| `get_full_system_report` | Complete analysis | All diagnostics in one comprehensive report |
## Installation
```bash
# Clone and setup
git clone <repository>
cd mcp-sysinfo
# Install dependencies
uv add fastmcp psutil requests
# Test the server
uv run python main.py
```
## Usage
### MCP Configuration
Add to your MCP client configuration:
#### Local/stdio Configuration
```json
{
"mcpServers": {
"sysinfo": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/mcp-sysinfo", "python", "main.py"]
}
}
}
```
#### Remote/HTTP Configuration
```json
{
"mcpServers": {
"sysinfo": {
"type": "http",
"url": "http://localhost:8000/mcp/"
}
}
}
```
For HTTP mode, set the `PORT` environment variable:
```bash
PORT=8000 uv run python main.py
```
### Tool Usage Examples
#### Quick System Check
```python
# Get essential system overview
result = await client.call_tool("get_system_summary", {})
```
#### Targeted Diagnostics
```python
# Network troubleshooting
network_info = await client.call_tool("get_network_status", {})
# Storage analysis
storage_info = await client.call_tool("get_storage_analysis", {})
# Security audit
ports_info = await client.call_tool("get_open_ports", {})
```
#### Complete System Analysis
```python
# Full diagnostic report
full_report = await client.call_tool("get_full_system_report", {})
```
## Platform Support
- **macOS** 10.15+ (tested on Apple Silicon)
- **Linux** Ubuntu/Debian-based distributions
- **Windows** 10/11 (basic support)
## Architecture
```
src/sysinfo/
├── __init__.py # Package exports
├── collectors.py # Modular info collection functions
└── server.py # FastMCP server implementation
main.py # Entry point
```
### Key Design Principles
- **Modular Tools**: Each diagnostic function is a separate MCP tool for targeted usage
- **Performance Optimized**: Raw text output without JSON wrapping overhead
- **Error-resilient**: Graceful handling of missing/inaccessible data
- **Cross-platform**: Platform-specific detection with intelligent fallbacks
- **Agent-friendly**: Clean markdown output optimized for LLM consumption
- **Minimal Dependencies**: Uses only `fastmcp`, `psutil`, and `requests`
## Development
### Testing
```bash
# Test with in-memory client
uv run python test_refactored.py
# Test individual collectors
uv run python -c "from src.sysinfo.collectors import get_hardware_info; print(get_hardware_info())"
```
### Adding New Collectors
1. Add function to `collectors.py`
2. Export in `__init__.py`
3. Call from `server.py` tool
4. Test cross-platform compatibility
## License
MIT License - see LICENSE file for details.