DeviceMCP
A cross-platform Model Context Protocol (MCP) server that provides device information including system specs, battery status, storage, and memory details for Windows, macOS, Linux, and Android.
Features
- 🖥️ Cross-Platform Support: Works on Windows, macOS, Linux, and Android (via Termux)
- 🔋 Battery Information: Get real-time battery level, charging status, and time remaining
- 💾 Storage Details: Monitor disk usage across all drives and partitions
- 🧠 Memory Stats: Track RAM and swap memory usage
- 📊 System Info: Access OS version, hostname, architecture, and processor details
- 🏗️ Modular Architecture: Clean, maintainable code with platform-specific implementations
Installation
Prerequisites
- Python 3.8 or higher
- pip or uv package manager
Install Dependencies
pip install -r requirements.txt
Or using uv:
uv pip install -r requirements.txt
For Android (Termux)
pkg install python
pip install fastmcp psutil pydantic
# Optional: Install termux-api for better battery info
pkg install termux-api
Usage
Run Locally (stdio transport)
python server.py
Or using FastMCP CLI:
fastmcp run server.py:mcp
Run with HTTP Transport
python server.py --transport http --port 8000
Or using FastMCP CLI:
fastmcp run server.py:mcp --transport http --port 8000
Install in Claude Desktop
Generate the configuration file:
fastmcp install server.py:mcp --name DeviceMCP
Then follow the prompts to install it in Claude Desktop.
Available Tools
1. get_device_info
Get comprehensive device information.
Returns:
{
"os_name": "Windows",
"os_version": "11",
"hostname": "MY-LAPTOP",
"architecture": "x86_64",
"processor": "Intel Core i7-9750H",
"platform": "windows"
}
2. get_battery_level
Get battery information and charging status.
Returns:
{
"percentage": 85.5,
"is_charging": true,
"is_plugged": true,
"time_remaining": 3600,
"time_remaining_formatted": "1h 0m",
"has_battery": true
}
3. get_storage_info
Get storage information for all drives/partitions.
Returns:
[
{
"total_bytes": 512000000000,
"used_bytes": 256000000000,
"free_bytes": 256000000000,
"usage_percent": 50.0,
"mount_point": "C:\\",
"total_formatted": "476.84 GB",
"used_formatted": "238.42 GB",
"free_formatted": "238.42 GB"
}
]
4. get_memory_info
Get RAM and swap memory information.
Returns:
{
"total_bytes": 16000000000,
"available_bytes": 8000000000,
"used_bytes": 8000000000,
"usage_percent": 50.0,
"swap_total_bytes": 4000000000,
"swap_used_bytes": 1000000000,
"total_formatted": "14.90 GB",
"available_formatted": "7.45 GB",
"used_formatted": "7.45 GB",
"swap_total_formatted": "3.73 GB",
"swap_used_formatted": "953.67 MB"
}
5. get_system_summary
Get all device information in one comprehensive call.
Returns: Combined output of all the above tools plus platform detection.
Project Structure
devicemcp/
├── README.md # This file
├── requirements.txt # Python dependencies
├── fastmcp.json # FastMCP configuration
├── server.py # Main MCP server entry point
├── core/
│ ├── __init__.py
│ ├── base.py # Abstract base classes
│ └── models.py # Pydantic data models
├── platforms/
│ ├── __init__.py
│ ├── windows.py # Windows implementation
│ ├── macos.py # macOS implementation
│ ├── linux.py # Linux implementation
│ └── android.py # Android implementation
└── utils/
├── __init__.py
├── platform_detector.py # Platform auto-detection
└── formatters.py # Output formatting utilities
Architecture
The project follows a modular architecture with clear separation of concerns:
- Core Layer: Abstract base classes and data models
- Platform Layer: Platform-specific implementations
- Utils Layer: Helper functions for detection and formatting
- Server Layer: FastMCP server with tool definitions
Each platform provider implements the DeviceInfoProvider interface, ensuring consistent behavior across all platforms.
Extending the Server
Adding a New Platform
- Create a new file in
platforms/(e.g.,bsd.py) - Implement the
DeviceInfoProviderinterface - Add platform detection logic in
utils/platform_detector.py - Import and register in the factory function
Adding New Metrics
- Add new models in
core/models.py - Add abstract methods in
core/base.py - Implement in each platform provider
- Add tool function in
server.py
Development
Running Tests
pytest tests/
Code Style
The project follows PEP 8 style guidelines. Format code with:
black .
isort .
Troubleshooting
Battery Information Not Available
Some desktop systems don't have batteries. The server will return has_battery: false in such cases.
Permission Errors on Storage Info
Some drives/partitions may require elevated permissions. The server silently skips inaccessible drives.
Android Battery Info
For best results on Android, install termux-api:
pkg install termux-api
License
MIT License - feel free to use this in your own projects!
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
Support
For issues and questions, please open an issue on the GitHub repository.