🖥️ 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

🔧 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

Related MCP server: MCP Personal Assistant Agent

📥 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

1. Clone the repository:

   git clone https://github.com/guangxiangdebizi/windows-system-mcp.git
   cd windows-system-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Local Development (Stdio)

If installed globally:

windows-system-mcp

If built from source:

npm start

Development

For development with auto-rebuild:

npm run dev

SSE Deployment (Supergateway)

If installed globally:

npx supergateway --stdio "windows-system-mcp" --port 3100

If built from source:

npm run sse

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
}

System Information

// 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

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 file for details.

🔗 Links

• NPM Package: https://www.npmjs.com/package/windows-system-mcp

• GitHub: https://github.com/guangxiangdebizi/windows-system-mcp

• Author: Xingyu Chen

• Email: guangxiangdebizi@gmail.com

• NPM Profile: https://www.npmjs.com/~xingyuchen

👨‍💻 Author

Xingyu Chen

• 🌐 Website: GitHub Profile

• 📧 Email: guangxiangdebizi@gmail.com

• 💼 LinkedIn: Xingyu Chen

• 📦 NPM: @xingyuchen

🙏 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