README.md•8.31 kB
# 🖥️ Windows System MCP
[](https://www.npmjs.com/package/windows-system-mcp)
[](https://www.npmjs.com/package/windows-system-mcp)
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.typescriptlang.org/)
[](https://nodejs.org/)
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
### 🔧 System Information
- **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
### 📊 Performance Monitoring
- **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
```bash
# 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)
```bash
npm install -g windows-system-mcp
```
#### Option 2: Build from Source
1. **Clone the repository:**
```bash
git clone https://github.com/guangxiangdebizi/windows-system-mcp.git
cd windows-system-mcp
```
2. **Install dependencies:**
```bash
npm install
```
3. **Build the project:**
```bash
npm run build
```
### Local Development (Stdio)
**If installed globally:**
```bash
windows-system-mcp
```
**If built from source:**
```bash
npm start
```
### Development
For development with auto-rebuild:
```bash
npm run dev
```
### SSE Deployment (Supergateway)
**If installed globally:**
```bash
npx supergateway --stdio "windows-system-mcp" --port 3100
```
**If built from source:**
```bash
npm run sse
```
This will start the server on `http://localhost:3100/sse`
## 🔧 Configuration
### Claude Desktop Integration
#### Stdio Configuration
**If installed globally:**
```json
{
"mcpServers": {
"windows-system-mcp": {
"command": "windows-system-mcp"
}
}
}
```
**If built from source:**
```json
{
"mcpServers": {
"windows-system-mcp": {
"command": "node",
"args": ["path/to/windows-system-mcp/build/index.js"]
}
}
}
```
#### SSE Configuration
```json
{
"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
```typescript
// 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
```typescript
// 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
}
```
### System Information
```typescript
// 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
```typescript
// 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](CONTRIBUTING.md) for details.
### Development Setup
1. Fork the repository
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Make your changes
4. Add tests if applicable
5. Commit your changes: `git commit -m 'Add amazing feature'`
6. Push to the branch: `git push origin feature/amazing-feature`
7. Open a Pull Request
## 📄 License
This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.
## 🔗 Links
- **NPM Package**: [https://www.npmjs.com/package/windows-system-mcp](https://www.npmjs.com/package/windows-system-mcp)
- **GitHub**: [https://github.com/guangxiangdebizi/windows-system-mcp](https://github.com/guangxiangdebizi/windows-system-mcp)
- **Author**: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- **Email**: guangxiangdebizi@gmail.com
- **NPM Profile**: [https://www.npmjs.com/~xingyuchen](https://www.npmjs.com/~xingyuchen)
## 👨💻 Author
**Xingyu Chen**
- 🌐 Website: [GitHub Profile](https://github.com/guangxiangdebizi/)
- 📧 Email: guangxiangdebizi@gmail.com
- 💼 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- 📦 NPM: [@xingyuchen](https://www.npmjs.com/~xingyuchen)
## 🙏 Acknowledgments
- [Model Context Protocol](https://github.com/modelcontextprotocol) 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
---
<div align="center">
<strong>Built with ❤️ for the AI and Windows communities</strong>
</div>