内容
[](https://mseep.ai/app/cursortouch-windows-mcp)
<div align="center">
<h1>🪟 Windows-MCP</h1>
<a href="https://github.com/CursorTouch/Windows-MCP/blob/main/LICENSE">
<img src="https://img.shields.io/badge/license-MIT-green" alt="许可证">
</a>
<img src="https://img.shields.io/badge/python-3.13%2B-blue" alt="Python">
<img src="https://img.shields.io/badge/platform-Windows%207–11-blue" alt="平台: Windows 7 至 11">
<img src="https://img.shields.io/github/last-commit/CursorTouch/Windows-MCP" alt="最新提交">
<br>
<a href="https://x.com/CursorTouch">
<img src="https://img.shields.io/badge/follow-%40CursorTouch-1DA1F2?logo=twitter&style=flat" alt="关注 Twitter">
</a>
<a href="https://discord.com/invite/Aue9Yj2VzS">
<img src="https://img.shields.io/badge/Join%20on-Discord-5865F2?logo=discord&logoColor=white&style=flat" alt="加入 Discord">
</a>
</div>
<br>
**Windows-MCP** 是一个轻量级、开源的项目，实现了 AI 代理与 Windows 操作系统之间的无缝集成。作为 MCP 服务器，Windows-MCP 弥合了大型语言模型（LLM）与 Windows 操作系统之间的差距，允许代理执行文件导航、应用程序控制、UI 交互、QA 测试等任务。
mcp-name: io.github.CursorTouch/Windows-MCP
## 更新
- Windows-MCP 在 [Claude Desktop 扩展](https://claude.ai/directory) 中达到了 `2M+ 用户`。
- 试用使用 Windows-MCP 构建的代理 [🪟Windows-Use](https://pypi.org/project/windows-use/)。
- Windows-MCP 现已在 [PyPI](https://pypi.org/project/windows-mcp/) 上可用（支持 `uvx windows-mcp`）。
- Windows-MCP 已添加到 [MCP 注册表](https://github.com/modelcontextprotocol/registry)。
### 支持的操作系统
- Windows 7
- Windows 8, 8.1
- Windows 10
- Windows 11
## 🎥 演示
<https://github.com/user-attachments/assets/d0e7ed1d-6189-4de6-838a-5ef8e1cad54e>
<https://github.com/user-attachments/assets/d2b372dc-8d00-4d71-9677-4c64f5987485>
## ✨ 主要功能
- **无缝 Windows 集成**
与 Windows UI 元素原生交互，打开应用程序，控制窗口，模拟用户输入等。
- **使用任意 LLM（可选视觉）**
与许多自动化工具不同，Windows-MCP 不依赖传统的计算机视觉技术或特定的微调模型；它与任意 LLM 配合使用，减少了复杂性和设置时间。
- **丰富的 UI 自动化工具集**
包括用于基本键盘、鼠标操作和捕获窗口/UI 状态的工具。
- **轻量级和开源**
依赖项最少，设置简单，完整源代码在 MIT 许可证下可用。
- **可定制和可扩展**
轻松适应或扩展工具，以满足您独特的自动化或 AI 集成需求。
- **实时交互**
操作之间的典型延迟（例如，从一个鼠标点击到下一个）范围为 **0.2 到 0.5 秒**，并且可能会根据活动应用程序的数量、系统负载以及 LLM 的推理速度而略有不同。
- **浏览器自动化 DOM 模式**
特殊的 `use_dom=True` 模式，用于 State-Tool，专注于网页内容，过滤掉浏览器 UI 元素，实现更干净、更高效的网页自动化。支持 Chrome、Edge 和 Firefox（Firefox 使用 IAccessible2 作为备用，因为它不通过 UIA 公开 `RootWebArea`）。
## 🛠️安装
**注意：** 当您第一次安装此 MCP 服务器时，可能需要一两分钟，因为需要安装 `pyproject.toml` 中的依赖项。在第一次运行时，服务器可能会超时，请忽略它并重新启动。
### 先决条件
- Python 3.13+
- UV（包管理器）来自 Astra，使用 `pip install uv` 或 `curl -LsSf https://astral.sh/uv/install.sh | sh` 安装。
- Windows 中将英语设置为默认语言，否则在 Windows 中禁用 MCP 服务器的 `App-Tool`。
### 登录时运行
直接按需运行服务器：
```shell
uvx windows-mcp serve
uvx windows-mcp serve --transport sse --host localhost --port 8000
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000
```
将其安装为后台任务，现在启动并在每次登录时启动：
```shell
windows-mcp install
# 或显式选择 HTTP 传输和绑定地址
windows-mcp install --transport sse --host 127.0.0.1 --port 8000
```
这会创建一个名为 `windows-mcp-server` 的用户 Scheduled Task 和一个位于 `~/.windows-mcp/start-server.cmd` 的包装脚本。使用 `windows-mcp uninstall` 删除它。日志写入到 `~/.windows-mcp/server.log` 和 `~/.windows-mcp/server.error.log`。
<details>
<summary>在 Claude Desktop 中安装</summary>
1. 安装 [Claude Desktop](https://claude.ai/download)。
```shell
npm install -g @anthropic-ai/mcpb
```
2. 配置 MCP 服务器。
**选项 A：从 PyPI 安装（推荐）**
使用 `uvx` 直接从 PyPI 运行最新版本。
将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": [
"windows-mcp",
"serve"
]
}
}
}
```
**选项 B：从源代码安装**
1. 克隆存储库：
```shell
git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP
```
2. 将以下内容添加到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uv",
"args": [
"--directory",
"<path to the windows-mcp directory>",
"run",
"windows-mcp",
"serve"
]
}
}
}
```
3. 完全重启 Claude Desktop 并验证服务器是否出现在 MCP 工具列表中。
**Claude Desktop MSIX（Windows 应用商店）**
MSIX 打包的 Claude Desktop（Microsoft 应用商店版本）虚拟化了 `%APPDATA%`。这会导致两个主要问题：
1. 配置文件位于：`%LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json`（不是 `%APPDATA%\Claude\`）。
2. 由于 `${__dirname}` 变量解析为不正确的（非虚拟化）路径，因此无法从“Claude 目录”自动安装。
**在 Windows 应用商店版本的 Claude 上配置 Windows-MCP**
您必须手动编辑配置文件。请注意，MSIX 沙盒中的 Electron 应用程序不会继承系统 `PATH`，因此您必须使用 `uvx.exe`（或 `uv.exe`）的完整绝对路径。
**选项 A：使用预安装的可执行文件**
1. 在终端中运行 `uv tool install windows-mcp`。
2. 在您的配置中使用生成的可执行文件：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "C:\\Users\\<user>\\.local\\bin\\windows-mcp.exe",
"args": ["serve"]
}
}
}
```
**选项 B：使用 uvx**
```json
{
"mcpServers": {
"windows-mcp": {
"command": "C:\\Users\\<user>\\.local\\bin\\uvx.exe",
"args": ["windows-mcp", "serve"]
}
}
}
```
**选项 C：从源代码安装**
```json
{
"mcpServers": {
"windows-mcp": {
"command": "C:\\Users\\<user>\\.local\\bin\\uv.exe",
"args": [
"--directory",
"C:\\path\\to\\Windows-MCP",
"run",
"windows-mcp",
"serve"
]
}
}
}
```
将 `<user>` 替换为您的 Windows 用户名。要找到正确的路径，请运行 `where uvx`、`where windows-mcp` 或 `where uv`。完全退出 Claude Desktop（托盘 -> 退出）并在保存配置后重新打开。
有关其他 Claude Desktop 集成故障排除，请参阅 [MCP 文档](https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues)。
</details>
<details>
<summary>在 Perplexity Desktop 中安装</summary>
1. 安装 [Perplexity Desktop](https://apps.microsoft.com/detail/xp8jnqfbqh6pvf)。
2. 打开 Perplexity Desktop 并进入 `Settings -> Connectors -> Add Connector -> Advanced`。
3. 输入名称为 `Windows-MCP`，然后粘贴以下配置之一。
**选项 A：从 PyPI 安装（推荐）**
```json
{
"command": "uvx",
"args": [
"windows-mcp",
"serve"
]
}
```
**选项 B：从源代码安装**
```json
{
"command": "uv",
"args": [
"--directory",
"<path to the windows-mcp directory>",
"run",
"windows-mcp",
"serve"
]
}
```
4. 点击 `Save`，然后在需要时重启 Perplexity Desktop。
有关其他 Claude Desktop 集成故障排除，请参阅 [Perplexity MCP 支持](https://www.perplexity.ai/help-center/en/articles/11502712-local-and-remote-mcps-for-perplexity)。该文档包括有关检查日志和解决常见问题的有帮助的提示。
</details>
<details>
<summary> 在 Gemini CLI 中安装</summary>
1. 安装 Gemini CLI。
```shell
npm install -g @google/gemini-cli
```
2. 打开 `%USERPROFILE%/.gemini/settings.json`。
3. 添加 `windows-mcp` 配置并保存。
```json
{
"theme": "Default",
...
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": [
"windows-mcp",
"serve"
]
}
}
}
```
*注意：要从源代码运行，请将命令替换为 `uv`，参数替换为 `["--directory", "<path>", "run", "windows-mcp", "serve"]`.*
4. 重启 Gemini CLI。
</details>
<details>
<summary>在 Qwen Code 中安装</summary>
1. 安装 Qwen Code。
```shell
npm install -g @qwen-code/qwen-code@latest
```
2. 打开 `%USERPROFILE%/.qwen/settings.json`。
3. 添加 `windows-mcp` 配置并保存。
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": [
"windows-mcp",
"serve"
]
}
}
}
```
*注意：要从源代码运行，请将命令替换为 `uv`，参数替换为 `["--directory", "<path>", "run", "windows-mcp", "serve"]`.*
4. 重启 Qwen Code。
</details>
<details>
<summary>在 Codex CLI 中安装</summary>
1. 安装 Codex CLI。
```shell
npm install -g @openai/codex
```
2. 打开 `%USERPROFILE%/.codex/config.toml`。
3. 添加 `windows-mcp` 配置并保存。
```toml
[mcp_servers.windows-mcp]
command="uvx"
args=[
"windows-mcp",
"serve"
]
```
*注意：要从源代码运行，请将命令替换为 `uv`，参数替换为 `["--directory", "<path>", "run", "windows-mcp", "serve"]`.*
4. 重启 Codex CLI。
</details>
<details>
<summary>在 Claude Code 中安装</summary>
1. 安装 [Claude Code](https://docs.anthropic.com/en/docs/claude-code/overview)：
```shell
npm install -g @anthropic-ai/claude-code
```
2. 配置服务器：
**选项 A：从 PyPI 安装（推荐）**
使用 `uvx` 直接从 PyPI 运行最新版本。
```shell
claude mcp add --transport stdio windows-mcp -- uvx windows-mcp serve
```
**选项 B：从源代码安装**
1. 克隆存储库：
```shell
git clone https://github.com/CursorTouch/Windows-MCP.git
cd Windows-MCP
```
2. 在终端中运行以下命令：
```shell
claude mcp add --transport stdio windows-mcp -- uv --directory "<path>" run windows-mcp serve
```
*注意：要使服务器在所有项目中可用，请在命令中添加 `--scope user`.*
3. 重新运行 Claude Code。享受 🥳
**注意：** 在 Windows 上，如果您遇到“连接关闭”错误，请使用 `uvx.exe` 的完整路径：
```shell
claude mcp add --transport stdio windows-mcp -- C:\Users\<user>\.local\bin\uvx.exe windows-mcp serve
```
要验证服务器是否已已注册，请运行 `claude mcp list`。在 Claude Code 中，使用 `/mcp` 检查服务器状态。
**WSL（Windows 子系统 Linux）**
如果您从 WSL 运行 Claude Code，则 MCP 服务器仍必须在 Windows 端执行（它需要 Windows API 进行 UI 自动化）。使用 `powershell.exe` 作为命令来桥接 WSL 和 Windows：
1. 在 **Windows** 上安装 `uv`（从 PowerShell 终端）：
```powershell
irm https://astral.sh/uv/install.ps1 | iex
```
2. 从您的 **WSL 终端** 注册服务器：
```shell
claude mcp add windows-mcp --transport stdio -s user -- powershell.exe -Command "C:\Users\<user>\.local\bin\uvx.exe windows-mcp serve"
```
将 `<user>` 替换为您的 Windows 用户名。`-s user` 标志使服务器在所有项目中可用。
3. 重启 Claude Code 并使用 `/mcp` 验证。
</details>
---
## 🖥️运行 Windows-MCP
Windows-MCP 直接在您的 Windows 机器上运行，并向连接的 MCP 客户端公开其工具。
```shell
# 使用 stdio 传输（默认）运行
uvx windows-mcp serve
# 或使用 SSE/Streamable HTTP 进行网络访问
uvx windows-mcp serve --transport sse --host localhost --port 8000
uvx windows-mcp serve --transport streamable-http --host localhost --port 8000
```
可以根据需要设置可选的环境变量 - 请参见下面的 [环境变量](#-environment-variables)。
### 远程访问的安全性
对于网络访问，请启用身份验证和 TLS：
```shell
windows-mcp serve --transport sse --host 0.0.0.0 \
--auth-key "your_secret_token" \
--ip-allowlist "203.0.113.0/24" \
--ssl-certfile cert.pem --ssl-keyfile key.pem
```
有关所有选项，请参阅 [🔐 安全性和访问控制](#-security--access-control)。
### 传输选项
| 传输 | 命令 | 用例 |
|---|---|---|
| `stdio`（默认） | `serve --transport stdio` | 与 MCP 客户端（如 Claude Desktop、Cursor 等）直接连接 |
| `sse` | `serve --transport sse --host HOST --port PORT` | 通过 Server-Sent Events 可从网络访问 |
| `streamable-http` | `serve --transport streamable-http --host HOST --port PORT` | 通过 HTTP 流可从网络访问（推荐用于生产） |
---
## 🔐 安全性和访问控制
### 身份验证
```shell
windows-mcp serve --transport sse --host 0.0.0.0 --auth-key "your_token"
```
所有请求都需要 `Authorization: Bearer your_token` 头。
### IP 允许列表
```shell
windows-mcp serve --auth-key "token" --ip-allowlist "203.0.113.0/24,198.51.100.5"
```
限制连接到的指定 CIDR 范围。默认阻止私有/环回 IP 地址。
### CORS 来源
默认情况下，**不发出 CORS 头**。浏览器通过其同源策略阻止跨源请求，这意味着任意网站都无法访问 MCP 控制平面，即使服务器位于 `localhost`。还自动应用主机头验证（DNS 重绑定保护），基于绑定地址。
如果您需要基于浏览器的 MCP 客户端访问服务器，请使用显式来源允许列表选择加入：
```shell
windows-mcp serve --cors-origins "https://my-client.example.com,https://other.example.com"
```
只有列出的来源才会收到 `Access-Control-Allow-Origin` 头；所有其他跨源请求都会被浏览器拒绝。等效的环境变量是 `WINDOWS_MCP_CORS_ORIGINS`。
### 工具选择
默认情况下，所有工具都已启用。使用 `--tools` 来允许特定的工具，或使用 `--exclude-tools` 来阻止特定的工具。
```shell
windows-mcp serve --tools "Screenshot,Click,Snapshot" # 仅启用这些工具
windows-mcp serve --exclude-tools "PowerShell,Registry" # 禁用特定工具
```
### TLS/HTTPS
```shell
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes
windows-mcp serve --ssl-certfile cert.pem --ssl-keyfile key.pem
```
### OAuth 2.0 + PKCE
对于使用 OAuth 的 MCP 客户端（例如 Claude Desktop）：
```shell
windows-mcp serve --transport streamable-http --host 0.0.0.0 \
--ssl-certfile ~/.windows-mcp/cert.pem \
--ssl-keyfile ~/.windows-mcp/key.pem \
--oauth-client-id my-client \
--oauth-client-secret my-secret
```
**Claude Desktop 配置：**
```json
{
"mcpServers": {
"windows-mcp": {
"type": "http",
"url": "https://<host>:8000/mcp/",
"oauth": {
"clientId": "my-client",
"clientSecret": "my-secret"
}
}
}
}
```
OAuth 服务器公开：
- `GET /.well-known/oauth-authorization-server` — 服务器元数据（RFC 8414）
- `GET /oauth/authorize` — 授权代码 + PKCE（需要 `S256`）
- `POST /oauth/token` — 令牌交换（需要客户端密钥）
- `POST /oauth/register` — 禁用；客户端必须预先配置
动态客户端注册已禁用。重定向 URI 必须仅限环回 `http(s)`。
身份验证密钥和 OAuth 可以共存 — 两者都接受为有效的 Bearer 令牌。
### 配置文件 (`~/.windows-mcp/config.toml`)
与其每次都传递标志，不如将您的配置存储在 `~/.windows-mcp/config.toml` 中。CLI 标志始终覆盖配置文件值。
**搜索顺序：**
1. `--config /path/to/config.toml`
2. `~/.windows-mcp/config.toml`
**stdio** — 本地仅限，无需安全保护：
```toml
[server]
transport = "stdio"
```
**SSE** — 网络访问，带有身份验证和 IP 限制：
```toml
[server]
transport = "sse"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
[security]
ip_allowlist = ["192.168.1.0/24"]
```
**Streamable HTTP** — 带有身份验证、TLS 和工具排除：
```toml
[server]
transport = "streamable-http"
host = "0.0.0.0"
port = 8000
auth_key = "your-secret-key"
ssl_certfile = "cert.pem" # 相对于 ~/.windows-mcp/
ssl_keyfile = "key.pem"
[security]
ip_allowlist = ["192.168.1.0/24"]
cors_origins = ["https://my-client.example.com"] # 可选 — 浏览器 CORS 选择加入
oauth_client_id = "my-client" # 可选 — 启用 OAuth 2.0 + PKCE
oauth_client_secret = "my-secret"
[tools]
exclude = ["PowerShell", "Registry"] # 禁用特定工具
```
将证书和密钥文件放在同一目录中：
```
~/.windows-mcp/
├── config.toml
├── cert.pem
└── key.pem
```
直接在该目录中生成自签名证书：
```shell
mkdir -p ~/.windows-mcp
openssl req -x509 -newkey rsa:4096 \
-keyout ~/.windows-mcp/key.pem \
-out ~/.windows-mcp/cert.pem \
-days 365 -nodes
```
### `auth` 辅助工具
生成身份验证密钥并将有效的配置文件保存到 `~/.windows-mcp/config.toml`：
```shell
windows-mcp auth
```
生成身份验证密钥和自签名 TLS 证书：
```shell
windows-mcp auth --transport streamable-http --host 0.0.0.0 --port 8000 --with-tls
```
此命令会将身份验证密钥写入配置文件中，可以生成 `cert.pem` 和 `key.pem`，并为选定的传输方式打印示例 MCP 客户端配置。
### SSRF 防护
`Scrape` 工具阻止：私有 IP 地址、环回地址、链路本地地址、URL 中的凭证、非 HTTP 方案。
---
## ⚙️ 环境变量
所有变量都是可选的，除非特别注明。可以通过 `claude_desktop_config.json` 中的 `env` 键（或 MCP 客户端的等效配置）来设置它们。
### 截图和快照
| 变量 | 默认值 | 描述 |
|---|---|---|
| `WINDOWS_MCP_SCREENSHOT_SCALE` | `1.0` | 应用于截图的缩放因子，缩放后编码。接受范围为 `0.1`–`1.0` 的浮点数。对于高分辨率显示屏（1440p、4K），默认设置可能会使图像超过 Claude Desktop 的 1 MB 工具结果限制。设置为 `0.5` 可以将两个维度都缩小一半（四分之一文件大小）。 |
| `WINDOWS_MCP_SCREENSHOT_BACKEND` | `auto` | 截图捕获后端。接受的值：`auto`（按顺序尝试 dxcam → mss → pillow）、`dxcam`、`mss`、`pillow`。如果 `dxcam` 无法使用或在您的 GPU 上引起问题，请使用 `mss` 或 `pillow`。 |
| `WINDOWS_MCP_PROFILE_SNAPSHOT` | _(禁用)_ | 设置为 `1`、`true`、`yes` 或 `on` 以发出每阶段计时日志，用于截图/快照调用。对于诊断慢速捕获非常有用。 |
| `WINDOWS_MCP_DISABLE_FLASH` | _(禁用)_ | 设置为 `1`、`true`、`yes` 或 `on` 以抑制橙红色发光边框，该边框在每次截图后短暂高亮显示捕获区域。闪光效果在捕获后会在透明的始终置顶窗口上渲染，因此它永远不会出现在捕获的图像中。 |
### 安全
| 变量 | 默认值 | 描述 |
|---|---|---|
| `WINDOWS_MCP_AUTH_KEY` | _(无)_ | 所有 HTTP 请求所需的 Bearer 令牌。 `--auth-key` CLI 标志的替代方法。 |
| `WINDOWS_MCP_IP_ALLOWLIST` | _(无)_ | 允许的客户端 IP 地址或 CIDR 范围的逗号分隔列表（例如，`203.0.113.0/24,198.51.100.5`）。 `--ip-allowlist` CLI 标志的替代方法。 |
| `WINDOWS_MCP_CORS_ORIGINS` | _(无)_ | 允许进行跨源浏览器请求的源的逗号分隔列表（例如，`https://my-client.example.com`）。未设置时，不会发出 CORS 头部。 `--cors-origins` CLI 标志的替代方法。 |
| `WINDOWS_MCP_TOOLS` | _(所有工具启用)_ | 要启用的工具的逗号分隔显式列表（例如，`Screenshot,Click,Snapshot`）。 `--tools` CLI 标志的替代方法。 |
| `WINDOWS_MCP_EXCLUDE_TOOLS` | _(无)_ | 要禁用的工具的逗号分隔列表（例如，`PowerShell,Registry`）。 `--exclude-tools` CLI 标志的替代方法。 |
| `WINDOWS_MCP_SSL_CERTFILE` | _(无)_ | HTTPS 的 TLS 证书文件（.pem）的路径。必须与 `WINDOWS_MCP_SSL_KEYFILE` 一起提供。 |
| `WINDOWS_MCP_SSL_KEYFILE` | _(无)_ | HTTPS 的 TLS 私钥文件（.pem）的路径。必须与 `WINDOWS_MCP_SSL_CERTFILE` 一起提供。 |
| `WINDOWS_MCP_OAUTH_CLIENT_ID` | _(无)_ | HTTP 传输的 OAuth 客户端 ID。必须与 `WINDOWS_MCP_OAUTH_CLIENT_SECRET` 一起提供。 |
| `WINDOWS_MCP_OAUTH_CLIENT_SECRET` | _(无)_ | HTTP 传输的 OAuth 客户端密钥。必须与 `WINDOWS_MCP_OAUTH_CLIENT_ID` 一起提供。 |
| `WINDOWS_MCP_STATELESS_HTTP` | `false` | 设置为 `1`、`true`、`yes` 或 `on` 以在没有 `Mcp-Session-Id` 连接状态的情况下运行 `streamable-http`。对于重启后重新连接和水平缩放部署非常有用。 |
### 遥测
| 变量 | 默认值 | 描述 |
|---|---|---|
| `ANONYMIZED_TELEMETRY` | `true` | 设置为 `false` 以禁用匿名使用情况遥测。无论此设置如何，都不会收集个人数据、工具参数或输出。 |
| `POSTHOG_API_KEY` | 项目默认值 | 重写用于匿名遥测的 PostHog 项目写入密钥。设置为一个空字符串以跳过 PostHog 客户端初始化。 |
| `POSTHOG_HOST` | `https://us.i.posthog.com` | 重写用于匿名遥测的 PostHog 主机，例如用于自托管 PostHog 部署。 |
### 调试
| 变量 | 默认值 | 描述 |
|---|---|---|
| `WINDOWS_MCP_DEBUG` | `false` | 设置为 `1`、`true`、`yes` 或 `on` 以启用调试模式，该模式将日志级别设置为 DEBUG 以输出详细日志。也可以作为 `--debug` CLI 标志使用。 |
**示例 `claude_desktop_config.json`：**
本地（无安全保护）：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": ["windows-mcp", "serve"],
"env": { "WINDOWS_MCP_SCREENSHOT_SCALE": "0.5" }
}
}
}
```
远程（带有身份验证 + IP 允许列表 + TLS）：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": ["windows-mcp", "serve", "--transport", "sse", "--host", "0.0.0.0"],
"env": {
"WINDOWS_MCP_AUTH_KEY": "your_token",
"WINDOWS_MCP_IP_ALLOWLIST": "203.0.113.0/24",
"WINDOWS_MCP_SSL_CERTFILE": "/path/to/cert.pem",
"WINDOWS_MCP_SSL_KEYFILE": "/path/to/key.pem"
}
}
}
}
```
---
## 🔨MCP 工具
MCP 客户端可以访问以下工具与 Windows 进行交互：
- `Click`：在给定坐标处点击屏幕。
- `Type`：在元素上输入文本（可选清除现有文本）。
- `Scroll`：在窗口或特定区域垂直或水平滚动。
- `Move`：移动鼠标指针或拖动（设置 drag=True）到坐标。
- `Shortcut`：按下键盘快捷键（`Ctrl+c`、`Alt+Tab` 等）。
- `Wait`：暂停定义的时间。
- `WaitFor`：等待文本、活动窗口、元素或聚焦元素出现，通过在单个工具调用中轮询 UI 状态。
- `Screenshot`：快速截图桌面捕获，带有光标位置、活动/打开窗口和图像。跳过 UI 树提取以提高速度，应作为主要需要视觉上下文时的默认首选调用。支持 `display=[0]` 或 `display=[0,1]` 以捕获特定屏幕。捕获后，绘制一个简短的橙红色发光边框作为视觉确认（设置 `WINDOWS_MCP_DISABLE_FLASH=1` 以禁用）。
- `Snapshot`：完整的桌面状态捕获，用于需要交互式元素 ID、滚动区域或 `use_dom=True` 浏览器提取的工作流。支持 `use_vision=True` 以包含截图和 `display=[0]` 或 `display=[0,1]` 以限制所有返回的快照信息到特定屏幕。
- `App`：从开始菜单启动应用程序，调整或移动窗口，在应用程序之间切换。
- `PowerShell`：执行 PowerShell 命令。
- `FileSystem`：读取、写入、复制、移动、删除、列出、搜索和检查文件和目录。
- `Scrape`：从整个网页中抓取信息。
- `MultiSelect`：使用可选的 Ctrl 键选择多个项目（文件、文件夹、复选框）。当提供标签时，使用批量标签到坐标解析。
- `MultiEdit`：在指定坐标的多个输入字段中输入文本。当提供标签时，使用批量标签到坐标解析。
- `Clipboard`：读取或设置 Windows 剪贴板内容。
- `Process`：列出正在运行的进程或通过 PID 或名称终止它们。
- `Notification`：发送带有标题和消息的 Windows toast 通知。
- `Registry`：读取、写入、删除或列出 Windows 注册表值和键。
## 🤝 联系我们
保持更新并加入我们的社区：
- 📢 在 [X](https://x.com/CursorTouch) 上关注我们以获取最新新闻和更新
- 💬 加入我们的 [Discord 社区](https://discord.com/invite/Aue9Yj2VzS)
## 星级历史
[](https://www.star-history.com/#CursorTouch/Windows-MCP&Date)
## 👥 贡献者
感谢所有为 Windows-MCP 做出贡献的优秀人士！ 🎉
<a href="https://github.com/CursorTouch/Windows-MCP/graphs/contributors">
<img src="https://contrib.rocks/image?repo=CursorTouch/Windows-MCP" />
</a>
我们感谢每一次贡献，无论是代码、文档、错误报告还是功能建议。想贡献吗？请查看我们的 [贡献指南](CONTRIBUTING)！
## 🔒 安全
**重要**：Windows-MCP 以完全系统访问权限运行，可以执行不可逆操作。在部署前，请查看我们的全面安全指南。
有关详细的安全信息，包括：
- 工具特定的风险评估
- 部署建议
- 漏洞报告程序
- 合规性和审计指南
请阅读我们的 [安全政策](SECURITY.md)。
## 📊 遥测
Windows-MCP 收集使用数据以帮助改进 MCP 服务器。不会跟踪个人数据、工具参数或输出。
要禁用遥测，请在 MCP 客户端配置中将 `ANONYMIZED_TELEMETRY` 设置为 `false`：
```json
{
"mcpServers": {
"windows-mcp": {
"command": "uvx",
"args": [
"windows-mcp",
"serve"
],
"env": {
"ANONYMIZED_TELEMETRY": "false"
}
}
}
}
```
有关可配置选项的完整列表，请参见 [环境变量](#-环境变量) 部分。
有关收集的数据以及如何处理的详细信息，请参阅我们的安全策略中的 [遥测和数据隐私](SECURITY.md#telemetry-and-data-privacy) 部分。
## 📝 限制
- 选择段落中的特定文本部分，因为 MCP 依赖于 a11y 树。（⌛ 正在开发中。）
- `Type-Tool` 用于输入文本，而不是在 IDE 中编程，因为它一次输入整个程序。（⌛ 正在开发中。）
- 此 MCP 服务器不能用于玩视频游戏 🎮。
## 🪪 许可证
该项目在 MIT 许可证下许可 - 有关详细信息，请参见 [LICENSE](LICENSE) 文件。
## 🙏 致谢
Windows-MCP 利用了几个优秀的开源项目来支持其 Windows 自动化功能：
- [UIAutomation](https://github.com/yinkaisheng/Python-UIAutomation-for-Windows)
对这些库的维护者和贡献者表示巨大的感谢，感谢他们出色的工作和开源精神。
## 🤝 贡献
欢迎贡献！请参阅 [CONTRIBUTING](CONTRIBUTING) 以获取设置说明和开发指南。
由 [CursorTouch](https://github.com/CursorTouch) 用 ❤️ 制作
## 引用
```bibtex
@software{
author = {CursorTouch},
title = {Windows-MCP: 集成 LLM 代理与 Windows 的轻量级开源项目},
year = {2024},
publisher = {GitHub},
url={https://github.com/CursorTouch/Windows-MCP}
}
```
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器