Content
# Windows MCP.Net
A .NET-based Windows desktop automation MCP (Model Context Protocol) server that provides AI assistants with the ability to interact with the Windows desktop environment.
## 🚀 Features
### Core Features
- **Application Launching**: Start applications from the Start menu by name
- **PowerShell Integration**: Execute PowerShell commands and return results
- **Desktop State Capture**: Retrieve the current desktop state, including active applications, UI elements, etc.
- **Clipboard Operations**: Copy and paste text content
- **Mouse Operations**: Click, drag, and move the mouse cursor
- **Keyboard Operations**: Text input, key operations, and keyboard shortcuts
- **Window Management**: Resize and reposition windows, switch applications
- **Scrolling Operations**: Perform scrolling at specified coordinates
- **Web Scraping**: Retrieve web content and convert it to Markdown format
- **Screenshot Functionality**: Capture the screen and save it to a temporary directory
- **Wait Control**: Add delays between operations
### Supported Tools
| Tool Name | Function Description |
|-----------|---------------------|
| **LaunchTool** | Launch applications from the Start menu |
| **PowershellTool** | Execute PowerShell commands and return status codes |
| **StateTool** | Capture desktop state information, including applications and UI elements |
| **ClipboardTool** | Clipboard copy and paste operations |
| **ClickTool** | Mouse click operations (supports left, right, middle buttons, single, double, and triple clicks) |
| **TypeTool** | Input text at specified coordinates, supports clearing and pressing Enter |
| **ResizeTool** | Resize and reposition windows |
| **SwitchTool** | Switch to a specified application window |
| **ScrollTool** | Scroll at specified coordinates or current mouse position |
| **DragTool** | Drag from source coordinates to target coordinates |
| **MoveTool** | Move the mouse cursor to specified coordinates |
| **ShortcutTool** | Execute keyboard shortcut combinations |
| **KeyTool** | Press a single keyboard key |
| **WaitTool** | Pause execution for a specified number of seconds |
| **ScrapeTool** | Scrape web content and convert it to Markdown format |
| **ScreenshotTool** | Capture the screen and save it to a temporary directory, returning the image path |
## 📸 Demo Screenshots
### Text Input Demo
Automatically input text into Notepad using TypeTool:
### Web Search Demo
Open and search web content using ScrapeTool:
## 🛠️ Tech Stack
- **.NET 10.0**: Based on the latest .NET framework
- **Model Context Protocol**: Communication using the MCP protocol
- **Microsoft.Extensions.Hosting**: Application hosting framework
- **Serilog**: Structured logging
- **HtmlAgilityPack**: HTML parsing and web scraping
- **ReverseMarkdown**: HTML to Markdown conversion
## 📦 Installation
### Prerequisites
- Windows operating system
- .NET 10.0 Runtime or higher
**Important Note**: This project requires .NET 10 to run. Please ensure that .NET 10 is installed on your local machine. If not installed, visit the [.NET 10 download page](https://dotnet.microsoft.com/en-us/download/dotnet/10.0) for download and installation.
### Build from Source
```bash
# Clone the repository
git clone https://github.com/xuzeyu91/Windows-MCP.Net.git
cd Windows-MCP.Net/src
# Build the project
dotnet build
# Run the project
dotnet run
```
### Install NuGet Package
```bash
dotnet tool install --global WindowsMCP.Net
```
## 🚀 Usage
### Run as MCP Server
```bash
# Run directly
dotnet run --project src/Windows-MCP.Net.csproj
# Or use the installed tool
windows-mcp-net
```
### MCP Client Configuration
Add the following configuration to your MCP client configuration:
#### Using Globally Installed Tool (Recommended)
```json
{
"mcpServers": {
"WindowsMCP.Net": {
"type": "stdio",
"command": "dnx",
"args": ["WindowsMCP.Net@", "--yes"],
"env": {}
}
}
}
```
#### Running Directly from Project Source (Development Mode)
**Method 1: Workspace Configuration**
Create a `.vscode/mcp.json` file in the project root directory:
```json
{
"mcpServers": {
"WindowsMCP.Net-Dev": {
"type": "stdio",
"command": "dotnet",
"args": ["run", "--project", "src/Windows-MCP.Net.csproj"],
"cwd": "${workspaceFolder}",
"env": {}
}
}
}
```
**Method 2: User Configuration**
Run `MCP: Open User Configuration` from the VS Code command palette and add:
```json
{
"mcpServers": {
"WindowsMCP.Net-Local": {
"type": "stdio",
"command": "dotnet",
"args": ["run", "--project", "src/Windows-MCP.Net.csproj"],
"env": {}
}
}
}
```
> **Note**: Using the project source method is convenient for development and debugging, as changes to the code take effect without needing to reinstall. VS Code version 1.102+ supports automatic discovery and management of MCP servers.
## 📖 API Documentation
### Example Operations
#### Launch Application
```json
{
"tool": "LaunchTool",
"parameters": {
"name": "notepad"
}
}
```
#### Click Operation
```json
{
"tool": "ClickTool",
"parameters": {
"x": 100,
"y": 200,
"button": "left",
"clicks": 1
}
}
```
#### Text Input
```json
{
"tool": "TypeTool",
"parameters": {
"x": 100,
"y": 200,
"text": "Hello, World!",
"clear": false,
"pressEnter": false
}
}
```
#### Get Desktop State
```json
{
"tool": "StateTool",
"parameters": {
"useVision": false
}
}
```
#### Capture Screen
```json
{
"tool": "ScreenshotTool",
"parameters": {}
}
```
## 🏗️ Project Structure
```
src/
├── .mcp/ # MCP server configuration
├── Exceptions/ # Custom exception classes
├── Models/ # Data models
├── Prompts/ # Prompt templates
├── Services/ # Core services
│ ├── DesktopService.cs # Desktop operation service implementation
│ └── IDesktopService.cs # Desktop service interface
├── Tools/ # MCP tool implementations
│ ├── ClickTool.cs # Click tool
│ ├── LaunchTool.cs # Launch tool
│ ├── TypeTool.cs # Input tool
│ └── ... # Other tools
├── Program.cs # Program entry point
├── Windows-MCP.Net.csproj # Project file
└── Windows-MCP.Net.sln # Solution file
```
## 🔧 Configuration
### Logging Configuration
The project uses Serilog for logging, with log files saved in the `logs/` directory:
- Console Output: Real-time log display
- File Output: Daily rolling, retaining 31 days
- Log Level: Debug and above
### Environment Variables
| Variable Name | Description | Default Value |
|---------------|-------------|---------------|
| `ASPNETCORE_ENVIRONMENT` | Runtime environment | `Production` |
## 📝 License
This project is open-source under the MIT License. Please refer to the [LICENSE](LICENSE) file for details.
## 🔗 Related Links
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [.NET Documentation](https://docs.microsoft.com/dotnet/)
- [Windows API Documentation](https://docs.microsoft.com/windows/win32/)
## 📞 Support
If you encounter issues or have suggestions, please:
1. Check the [Issues](https://github.com/xuzeyu91/Windows-MCP.Net/issues)
2. Create a new Issue
3. Join the discussion
---
**Note**: This tool requires appropriate Windows permissions to perform desktop automation operations. Please ensure it is used in a trusted environment.
