🖥️ Windows System MCP
A comprehensive Model Context Protocol (MCP) server that provides AI models with powerful Windows system management capabilities. This MCP enables AI assistants to interact with Windows systems through a secure, well-structured interface.
✨ Features
📁 File System Management
- Directory Browsing: Navigate and explore directory structures
- File Operations: Read files, get file information, and search for files
- Disk Analysis: Monitor disk usage and find large files
- Advanced Search: Pattern-based file searching with recursive options
⚙️ Process Management
- Process Monitoring: List and monitor running processes
- Resource Tracking: Track CPU and memory usage by process
- Process Control: Start, stop, and manage processes
- Process Tree: Visualize parent-child process relationships
- Hardware Details: CPU, memory, disk, and network adapter information
- OS Information: Windows version, updates, and system configuration
- Environment: Environment variables and system paths
- User Management: User accounts and current user information
📋 Registry Operations
- Registry Reading: Access Windows registry keys and values
- System Configuration: Retrieve system settings from registry
- Startup Programs: List programs that start with Windows
- Installed Software: Enumerate installed applications
🛠️ Service Management
- Service Control: Start, stop, and restart Windows services
- Service Monitoring: Monitor service status and dependencies
- Startup Services: Manage services that start automatically
- Service Search: Find services by name or description
🌐 Network Operations
- Network Diagnostics: Ping, traceroute, and connectivity testing
- Port Scanning: Check open ports and network connections
- Network Configuration: View adapters, IP configuration, and routing
- WiFi Management: List and manage WiFi profiles
- Real-time Metrics: CPU, memory, disk, and network performance
- Resource Analysis: Identify top resource-consuming processes
- Performance Counters: Access Windows performance counters
- System Health: Monitor overall system performance
📥 Installation
# Global installation (recommended)
npm install -g windows-system-mcp
# Or use directly with npx
npx windows-system-mcp
🚀 Quick Start
Prerequisites
- Windows 10/11
- Node.js 18+
- PowerShell 5.1+
Installation Options
Option 1: Install from NPM (Recommended)
npm install -g windows-system-mcp
Option 2: Build from Source
- Clone the repository:
git clone https://github.com/guangxiangdebizi/windows-system-mcp.git
cd windows-system-mcp
- Install dependencies:
- Build the project:
Local Development (Stdio)
If installed globally:
If built from source:
Development
For development with auto-rebuild:
SSE Deployment (Supergateway)
If installed globally:
npx supergateway --stdio "windows-system-mcp" --port 3100
If built from source:
This will start the server on http://localhost:3100/sse
🔧 Configuration
Claude Desktop Integration
Stdio Configuration
If installed globally:
{
"mcpServers": {
"windows-system-mcp": {
"command": "windows-system-mcp"
}
}
}
If built from source:
{
"mcpServers": {
"windows-system-mcp": {
"command": "node",
"args": ["path/to/windows-system-mcp/build/index.js"]
}
}
}
SSE Configuration
{
"mcpServers": {
"windows-system-mcp": {
"type": "sse",
"url": "http://localhost:3100/sse",
"timeout": 600
}
}
}
Note: For SSE mode, start the server first using the commands shown in the deployment section above.
📖 Usage Examples
File System Operations
// List directory contents
{
"action": "list_directory",
"path": "C:\\Users",
"recursive": true,
"max_depth": 2
}
// Search for files
{
"action": "search_files",
"pattern": "*.log",
"path": "C:\\Windows\\Logs",
"recursive": true
}
// Find large files
{
"action": "find_large_files",
"path": "C:\\",
"size_threshold": 500
}
Process Management
// List running processes
{
"action": "list_processes",
"sort_by": "cpu",
"limit": 20
}
// Get process details
{
"action": "get_process_details",
"process_name": "chrome"
}
// Kill a process
{
"action": "kill_process",
"process_id": 1234
}
// Get system overview
{
"action": "get_system_overview"
}
// Get hardware information
{
"action": "get_hardware_info",
"category": "cpu"
}
// Get environment variables
{
"action": "get_environment_vars",
"filter": "PATH"
}
Network Operations
// Ping a host
{
"action": "ping_host",
"host": "google.com",
"count": 4
}
// Scan ports
{
"action": "scan_open_ports",
"host": "localhost",
"port_range": "80,443,3000-3010"
}
// Get network adapters
{
"action": "get_network_adapters"
}
🛡️ Security Considerations
- Principle of Least Privilege: Run with minimal required permissions
- Input Validation: All inputs are validated and sanitized
- Safe Operations: Read-only operations are prioritized
- Error Handling: Comprehensive error handling prevents system exposure
- Audit Trail: All operations can be logged for security auditing
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Setup
- Fork the repository
- Create a feature branch:
git checkout -b feature/amazing-feature - Make your changes
- Add tests if applicable
- Commit your changes:
git commit -m 'Add amazing feature' - Push to the branch:
git push origin feature/amazing-feature - Open a Pull Request
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
🔗 Links
👨💻 Author
Xingyu Chen
🙏 Acknowledgments
- Model Context Protocol for the excellent MCP framework
- The Windows PowerShell team for providing powerful system management capabilities
- The TypeScript and Node.js communities for excellent tooling
📊 Project Stats
- NPM Package: Available as
windows-system-mcp - Language: TypeScript
- Runtime: Node.js
- Platform: Windows
- License: Apache 2.0
- MCP Version: 0.6.0