WinRemote MCP

WinRemote MCP--在Windows上远程运行MCP服务器

](https://pypi.org/project/winremote-mcp/)    ](https://pepy.tech/projects/winremote-mcp) 

用于远程桌面控制和自动化的终极Windows MCP服务器。 通过模型上下文协议控制任何Windows机器——非常适合人工智能代理Claude Desktop。将您的Windows桌面转换为功能强大、可远程访问的自动化端点。

快速启动（30秒）

# Install from PyPI
pip install winremote-mcp

# Start the Windows MCP server
winremote-mcp

就是这样！您的Windows MCP服务器现在正在上运行 http://127.0.0.1:8090 并准备接受来自Claude Desktop等MCP客户端的命令。

🤖 代理集成

winremote mcp与mcp兼容的AI代理和客户端协同工作。此仓库中提供了特定于客户端的设置指南：

• 赫尔墨斯 --添加winremote作为本机可流式传输HTTP或stdio MCP服务器。
• 开爪 --使用winremote作为OpenClaw的Windows控制层。
• 克劳德桌面/克劳德代码 --配置本地stdio或远程可流式传输HTTP。
• 光标 --将winremote添加到 .cursor/mcp.json.

Hermes设置

在Windows计算机上运行winremote mcp，然后将其作为mcp服务器添加到Hermes：

pip install winremote-mcp
winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"

mcp_servers:
  winremote:
    type: streamable-http
    url: http://:8090/mcp
    headers:
      Authorization: Bearer your-secret-key

查看完整 Hermes集成指南 用于本地stdio设置、验证提示和可用功能。

🤖 OpenClaw集成

winremote mcp是Windows的官方控制层 开爪它们共同为您的AI代理提供了对任何Windows机器的完全远程控制——屏幕截图、PowerShell、文件传输、GUI自动化等等。

______________________________________________________________________

最简单的方法：只需告诉OpenClaw

您不需要手动配置任何内容。只需告诉您的OpenClaw代理：

“在我的Windows计算机上安装winremote mcp 192.168.1.100 并将其与自己联系起来。Python安装在 C:\Python311\python.exe."

OpenClaw将通过SSH连接到Windows计算机，安装软件包，启动服务器，并连接MCP连接——所有这些都是自动完成的。

______________________________________________________________________

手动设置（逐步）

步骤1--在Windows上安装

pip install winremote-mcp

步骤2--启动服务器

仅本地快速启动（默认，最安全）：

winremote-mcp

远程访问需要身份验证：

从v0.4.20开始， winremote-mcp 拒绝在没有身份验证的情况下将HTTP传输绑定到非环回地址。使用API密钥进行LAN或远程访问：

winremote-mcp --host 0.0.0.0 --port 8090 --auth-key YOUR_SECRET_KEY

对于仅限实验室的遗留行为，您可以明确地承认风险 --allow-insecure-remote；不要在共享、路由或暴露于互联网的网络上使用此功能。

开机自动启动：

winremote-mcp install

第3步——连接OpenClaw

添加到您的 openclaw.json:

{
  "plugins": {
    "entries": {
      "winremote": {
        "type": "mcp",
        "url": "http://192.168.1.100:8090/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_SECRET_KEY"
        }
      }
    }
  }
}

或者告诉你的OpenClaw代理：

“在以下位置添加winremote MCP http://192.168.1.100:8090/mcp 带身份验证密钥 YOUR_SECRET_KEY."

第四步——你的代理人能做什么

连接后，您的AI代理可以完全控制Windows：

______________________________________________________________________

安全远程访问（HTTPS）

要通过互联网或不受信任的网络访问，请启用HTTPS：

步骤1——生成证书：

# Self-signed (LAN/homelab)
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Trusted cert (no browser warnings) — requires mkcert installed
mkcert -install && mkcert 192.168.1.100

步骤2——从TLS开始：

winremote-mcp --host 0.0.0.0 --port 8090 ^
  --auth-key YOUR_SECRET_KEY ^
  --ssl-certfile cert.pem ^
  --ssl-keyfile key.pem

使用HTTPS的OpenClaw配置：

{
  "plugins": {
    "entries": {
      "winremote": {
        "type": "mcp",
        "url": "https://192.168.1.100:8090/mcp",
        "headers": {
          "Authorization": "Bearer YOUR_SECRET_KEY"
        }
      }
    }
  }
}

______________________________________________________________________

OAuth 2.0（适用于Claude Desktop和其他MCP客户端）

一些MCP客户端（如Claude Desktop）使用OAuth而不是API密钥。OAuth是一个预先配置的机密客户端流：在服务器上配置客户端ID和客户端密钥，然后将相同的值复制到客户端。动态客户端注册已禁用，重定向URI必须是环回的 http(s) URI。

winremote-mcp --host 0.0.0.0 --port 8090 ^
  --ssl-certfile cert.pem --ssl-keyfile key.pem ^
  --oauth-client-id my-client --oauth-client-secret my-secret

Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "winremote": {
      "type": "http",
      "url": "https://192.168.1.100:8090/mcp/",
      "oauth": {
        "clientId": "my-client",
        "clientSecret": "my-secret"
      }
    }
  }
}

______________________________________________________________________

winremote.toml --完整配置参考

放在您的工作目录中或 ~/.config/winremote/winremote.toml:

[server]
host         = "0.0.0.0"
port         = 8090
auth_key     = "your-secret-key"
# Optional break-glass flag for legacy trusted-LAN deployments only.
# Remote HTTP without auth is refused unless this is true.
allow_insecure_remote = false
ssl_certfile = "C:/certs/cert.pem"   # optional — enables HTTPS
ssl_keyfile  = "C:/certs/key.pem"    # optional — enables HTTPS

[security]
ip_allowlist        = ["192.168.1.0/24"]   # restrict to LAN only
oauth_client_id     = ""                    # optional OAuth client ID
oauth_client_secret = ""                    # optional OAuth secret

[tools]
exclude = ["ScreenRecord"]   # disable specific tools

______________________________________________________________________

注： winremote mcp是一个标准的mcp服务器，可与任何兼容mcp的客户端（Claude Desktop、Cursor、OpenClaw等）配合使用。

v0.4.21的新增功能

📚 README发行说明清理

• README现在只保留最新的三个 What's New 部分。
• 旧的发行说明现在指向完整 更新日志 以保持README的重点。

v0.4.20的新增功能

🔒 安全加固

• 默认情况下，远程HTTP访问现在需要身份验证。除非您进行配置，否则非环回绑定将被拒绝 --auth-key 或OAuth机密客户端身份验证。
• --allow-insecure-remote 仍然可用，但仅作为明确的遗留/仅限实验室的玻璃破碎选项。
• OAuth动态客户端注册已禁用。OAuth现在需要一个预先配置的具有客户端ID和客户端机密的机密客户端。
• OAuth现在需要PKCE S256 以及环回重定向URI。
• Scrape 和 PlaySound URL获取现在会阻止私有、环回、本地链接、多播、保留和未指定的目标，以降低SSRF风险。
• App 和 PlaySound 移动到第3层，因为它们可以启动程序或触发服务器端效果。

🛡️ CI和供应链检查

• 添加了使用Bandit、pip审计和zizmor的CI安全扫描。
• 提高了FastMCP、Pillow、Authlib、密码学、python多部分、pytest和Pygments的最低依赖版本。
• 收紧GitHub Actions权限，并将工作流操作固定到不可变的SHA。

v0.4.19的新增功能

🤖 Hermes集成

• 添加了Hermes设置指南，用于将winremote mcp连接为本地mcp服务器。
• 在此存储库中添加了特定于客户端的集成指南的README链接。

有关较旧的发行说明，请参阅完整 更新日志.

它解决了什么问题

• 远程Windows控制：通过标准化的MCP协议从任何地方控制Windows桌面
• AI代理集成：使Claude、GPT和其他AI代理能够与Windows GUI应用程序交互
• 跨平台自动化：弥合Linux/macOS开发环境与Windows目标之间的差距
• 无头Windows管理：管理Windows服务器和工作站，无需RDP或VNC开销

特性

• 桌面控制 --屏幕截图（JPEG压缩，多显示器），点击，键入，滚动，键盘快捷键
• 窗口管理 --聚焦窗口，最小化所有，启动/调整应用程序大小，支持多显示器
• 远程Shell访问 --支持工作目录的PowerShell命令执行
• 文件操作 --读取、写入、列出、搜索文件；base64编码的二进制传输
• 系统管理 --Windows注册表访问、服务管理、计划任务、进程控制
• 网络工具 --Ping主机，检查TCP端口，监控网络连接
• 高级功能 --OCR文本提取、屏幕录制（GIF）、带UI元素标签的带注释屏幕截图
• AI视觉支持 --通过AI视觉与Flutter、Electron、Qt和任何UI兼容。看 视觉引导
• 安全与认证 -可选的API密钥身份验证，默认情况下仅绑定本地主机

安装

来自PyPI（推荐）

pip install winremote-mcp

源自

git clone https://github.com/dddabtc/winremote-mcp.git
cd winremote-mcp
pip install .

具有可选依赖关系

# Install with OCR support (includes pytesseract)
pip install winremote-mcp[ocr]

# Install development dependencies
pip install winremote-mcp[test]

OCR设置（可选）

从屏幕截图中提取文本：

# 1. Install Tesseract OCR engine
winget install UB-Mannheim.TesseractOCR

# 2. Install with OCR dependencies
pip install winremote-mcp[ocr]

用法

基本用法

层级和工具控制

# Default: tier1 + tier2 enabled, tier3 disabled
winremote-mcp

# Enable destructive tier3 tools
winremote-mcp --enable-tier3

# Disable interactive tier2 (tier1 only)
winremote-mcp --disable-tier2

# Both together: tier1 + tier3 (tier2 disabled)
winremote-mcp --enable-tier3 --disable-tier2

# Backward-compatible: enable everything
winremote-mcp --enable-all

# Explicit tool list (highest precedence over tier flags)
winremote-mcp --tools Snapshot,Click,Type

# Remove specific tools from resolved set
winremote-mcp --enable-tier3 --exclude-tools Shell,FileWrite

配置文件(winremote.toml)

搜索顺序：

1. --config /path/to/winremote.toml
2. ./winremote.toml
3. ~/.config/winremote/winremote.toml

[server]
host = "127.0.0.1"
port = 8090
auth_key = ""
ssl_certfile = ""       # Path to SSL certificate for HTTPS
ssl_keyfile = ""        # Path to SSL private key for HTTPS

[security]
ip_allowlist = ["127.0.0.1", "192.168.1.0/24"]
enable_tier3 = false
disable_tier2 = false
oauth_client_id = ""    # Expected OAuth client ID (optional)
oauth_client_secret = "" # OAuth client secret for confidential clients

[tools]
enable = ["Snapshot", "Click", "Type"]
exclude = []

优先： CLI标志覆盖配置文件值；配置文件值覆盖默认值。

IP地址列表

# CLI
winremote-mcp --ip-allowlist 127.0.0.1,192.168.1.0/24

# Or via config [security].ip_allowlist

支持单IP和CIDR范围（IPv4/IPv6）。未分配的客户端收到HTTP 403时出现明显错误。

HTTPS/TLS

要启用HTTPS，请提供SSL证书和密钥文件：

winremote-mcp --ssl-certfile cert.pem --ssl-keyfile key.pem

或在 winremote.toml:

[server]
ssl_certfile = "/path/to/cert.pem"
ssl_keyfile  = "/path/to/key.pem"

生成自签名证书 （用于本地/LAN）：

openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

OAuth 2.0

WinRemote-MCP包含一个内置的OAuth 2.0授权服务器，与Claude Desktop和其他需要OAuth的MCP客户端兼容。

通过以下方式启用它：

winremote-mcp --oauth-client-id my-client --oauth-client-secret my-secret

或在 winremote.toml:

[security]
oauth_client_id     = "my-client"
oauth_client_secret = "my-secret"

Claude桌面配置 (claude_desktop_config.json):

{
  "mcpServers": {
    "winremote": {
      "type": "http",
      "url": "https://your-host:8080/mcp/",
      "oauth": {
        "clientId": "my-client",
        "clientSecret": "my-secret"
      }
    }
  }
}

OAuth服务器实现了：

• GET /.well-known/oauth-authorization-server --服务器元数据（RFC 8414）
• POST /oauth/register --动态客户端注册（RFC 7591）
• GET /oauth/authorize --授权码+PKC（RFC 7636）
• POST /oauth/token --代币兑换

健康检查

# Start MCP server (localhost only, no auth)
winremote-mcp

# Start with remote access and authentication
winremote-mcp --host 0.0.0.0 --port 8090 --auth-key "your-secret-key"

# Enable all tools including high-risk Tier 3 (Shell, FileWrite, etc.)
winremote-mcp --enable-all

# Start with hot reload for development
winremote-mcp --reload

MCP客户端配置

适用于克劳德桌面(claude_desktop_config.json):

{
  "mcpServers": {
    "winremote": {
      "command": "winremote-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

对于HTTP MCP客户端：

{
  "mcpServers": {
    "winremote": {
      "type": "streamable-http", 
      "url": "http://192.168.1.100:8090/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-key"
      }
    }
  }
}

开机自动启动

# Create Windows scheduled task
winremote-mcp install

# Remove scheduled task  
winremote-mcp uninstall

安全

工具分为三个风险等级。默认情况下，仅启用1-2级工具。

# Enable all tiers (use with caution)
winremote-mcp --enable-all

# Always use auth for remote access
winremote-mcp --host 0.0.0.0 --auth-key "your-secret-key"

看 安全.md 查看完整的安全指南。

工具

运作原理

graph LR
    A["MCP Client
(Claude/AI)"] -->|commands| B["WinRemote MCP
Server"]
    B -->|API calls| C["Windows APIs
(Win32/WMI/PS)"]
    C -->|results| B
    B -->|responses| A

运输选项：

• 标准：直接进程通信（Claude Desktop的理想选择）
• 超文本传输协议：带有可选身份验证的RESTful API（非常适合远程访问）

核心架构：

1. 工具层：40+Windows自动化工具（截图、点击、键入等）
2. 任务管理器：并发控制和任务取消
3. 传输层：基于stdio或HTTP的MCP协议
4. 安全层：可选的承载令牌身份验证

使用非标准UI框架

AnnotatedSnapshot 使用Win32 API来检测UI元素，这与 Flutter，电子，Qt，或自定义绘制的UI。三种解决方案：

快速示例 --不需要额外的工具：

You:    "Take a screenshot with Snapshot, find the Connect button, and click it."
Claude:  1. Calls Snapshot() → sees the Flutter app screenshot
         2. Vision identifies "Connect" button at (520, 340)
         3. Calls Click(x=520, y=340)

有关设置说明、体系结构图和比较基准的完整指南，请参阅 docs/vision-guide.md.

故障排除/常见问题

Q： MCP服务器未启动？

A. 检查Python版本（需要3.10+），并确保没有其他服务正在使用端口8090：

python --version
netstat -an | findstr :8090

Q： 无法从远程机器连接？

A. 使用 --host 0.0.0.0 绑定到所有接口（默认为仅限localhost）：

winremote-mcp --host 0.0.0.0 --auth-key "secure-key"

Q： 截图工具是否返回空/黑图像？

A. Windows可能已锁定或显示器已关闭。请确保：

• Windows已解锁，显示器处于活动状态
• 没有运行屏幕保护程序
• 对于多监视器设置，请指定 monitor 参数

Q： OCR不工作？

A. 安装Tesseract OCR引擎：

winget install UB-Mannheim.TesseractOCR
pip install winremote-mcp[ocr]

Q： 注册表/服务权限错误？

A. 以管理员权限运行：

# Right-click Command Prompt → "Run as administrator"
winremote-mcp

贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发设置

git clone https://github.com/dddabtc/winremote-mcp.git
cd winremote-mcp
pip install -e ".[test]"
pytest  # Run tests

致谢

受到启发 Windows MCP CursorTouch。感谢您通过MCP在Windows桌面自动化方面所做的开创性工作。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

______________________________________________________________________

准备好用AI自动化Windows了吗？ ⚡ 安装 winremote-mcp 并在30秒内将您最喜欢的AI代理连接到任何Windows计算机。