使用说明

Windows管理MCP服务器

一种模型上下文协议（MCP）服务器，通过WinRM和SSH PowerShell协议提供远程Windows服务器管理和故障排除功能。

目的

此MCP服务器为AI助手提供了一个安全的接口，用于通过WinRM（主）或SSH（回退）协议使用PowerShell命令远程连接到Windows服务器、诊断问题和应用解决方案。

特性

远程连接方法

WinRM（主） -用于本机Windows远程管理的Windows远程管理协议
- 支持HTTP（端口5985）和HTTPS（端口5986）
- NTLM和基本身份验证
- 本机PowerShell命令执行
SSH PowerShell（回退） -使用OpenSSH的服务器基于SSH的PowerShell执行
- 适用于Windows 10/Server 2019+内置OpenSSH
- WinRM不可用时自动回退
- 完整的PowerShell命令支持

可用工具

test_connection -使用ping、WinRM和SSH端口检查测试与Windows服务器的连接
diagnose_system -收集全面的系统信息以诊断问题
execute_command -在远程服务器上执行PowerShell或CMD命令
check_service -检查Windows服务状态并提供管理选项
troubleshoot_application -对崩溃或无法工作的特定应用程序进行故障排除
apply_solution -应用PowerShell解决方案脚本来修复已识别的问题
get_performance_metrics -获取当前的CPU、内存、磁盘和网络指标
view_logs -查看特定服务器和日期的故障排除日志

先决条件

Docker环境

启用MCP工具包的Docker桌面
Docker MCP CLI插件(docker mcp 命令）

目标Windows服务器

对于WinRM访问（推荐）：

WinRM已启用并配置(winrm quickconfig)
PowerShell远程处理已启用(Enable-PSRemoting)
WinRM的防火墙规则（端口5985/5986）
Docker容器的网络连接

对于SSH回退（可选）：

OpenSSH服务器已安装并正在运行
SSH端口22在防火墙中打开
PowerShell可通过SSH访问

安装

步骤1：克隆存储库

git clone https://github.com/Cosmicjedi/windows-admin-mcp.git
cd windows-admin-mcp

第二步：构建Docker镜像

docker build -t windows-admin-mcp-server .

步骤3：设置日志目录（可选）

# Create a local directory for logs
mkdir -p ~/windows-admin-logs

# Set as environment variable
export WINDOWS_ADMIN_LOG_DIR=~/windows-admin-logs

步骤4：创建自定义目录

# Create catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs

# Create or edit custom.yaml
nano ~/.docker/mcp/catalogs/custom.yaml

将此条目添加到custom.yaml：

version: 2
name: custom
displayName: Custom MCP Servers
registry:
  windows-admin:
    description: "Remote Windows server administration via WinRM and SSH"
    title: "Windows Admin MCP"
    type: server
    dateAdded: "2025-09-24T00:00:00Z"
    image: windows-admin-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: test_connection
      - name: diagnose_system
      - name: execute_command
      - name: check_service
      - name: troubleshoot_application
      - name: apply_solution
      - name: get_performance_metrics
      - name: view_logs
    env:
      - name: WINDOWS_ADMIN_LOG_DIR
        value: "/app/logs"
    metadata:
      category: monitoring
      tags:
        - windows
        - administration
        - troubleshooting
        - powershell
        - winrm
        - ssh
        - remote
      license: MIT
      owner: local

步骤5：更新注册表

# Edit registry file
nano ~/.docker/mcp/registry.yaml

在现有条目下添加此条目 registry: 按键：

registry:
  # ... existing servers ...
  windows-admin:
    ref: ""

步骤6：配置Claude桌面

查找您的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
视窗: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

编辑文件并添加自定义目录：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "[YOUR_HOME]/.docker/mcp:/mcp",
        "-v", "[YOUR_LOG_DIR]:/app/logs",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

步骤7：重新启动克劳德桌面

完全退出克劳德桌面
重新启动克劳德桌面
您的Windows管理工具应该出现！

用法示例

在Claude Desktop中，您可以问：

“使用用户名Administrator和密码测试与Windows服务器192.168.1.100的连接”
“诊断服务器SNOOPY上的‘飞行狗屋’应用程序崩溃的原因”
“检查服务器PROD-WEB-01上的Windows Update服务的状态”
“使用凭据admin/password从服务器DB-server-02获取性能指标”
“使用我的凭据在服务器APP-server上执行Get Process命令”
“排除IIS无法在WEB-SERVER-01上启动的原因”
“应用解决方案以重新启动Print-SERVER上的后台打印程序服务”
“显示服务器SNOOPY从今天开始的日志”
“在C:\Users\Administrator中找到test.log文件并读取其内容”

建筑

Claude Desktop → MCP Gateway → Windows Admin MCP Server
                                         ↓
                                    [WinRM/SSH]
                                         ↓
                                  Windows Servers
                                         ↓
                                   Local Log Files
                            (/app/logs/hostname-MMDDYYYY.log)

连接流程

主要方法：WinRM
- 尝试在端口5985上进行HTTP连接
- 如果HTTP失败，则在端口5986上回退到HTTPS
- 默认情况下使用NTLM身份验证，回退到Basic
回退方法：SSH PowerShell
- 通过SSH在端口22上连接
- 通过SSH会话执行PowerShell命令
- 适用于Windows OpenSSH服务器

日志管理

服务器会自动为每台服务器创建每日日志文件：

格式： {hostname}-{MMDDYYYY}.log
位置：可通过配置 WINDOWS_ADMIN_LOG_DIR 环境变量
违约： /app/logs 在容器中
包含所有已执行操作的带时间戳的条目

安全考虑

凭证实时传递，不存储
WinRM连接使用NTLM/基本身份验证
SSH连接使用密码身份验证
日志文件包含操作历史记录，但没有密码
在Docker容器中以非root用户身份运行
考虑使用HTTPS WinRM（端口5986）进行生产
实现与秘密服务器的凭据管理集成

Windows服务器配置

启用WinRM（推荐）

# Quick configuration
winrm quickconfig

# Or manual configuration
Enable-PSRemoting -Force
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*"
Set-Service WinRM -StartupType Automatic
Start-Service WinRM

# For HTTPS (more secure)
New-SelfSignedCertificate -DnsName "servername" -CertStoreLocation Cert:\LocalMachine\My
New-Item -Path WSMan:\LocalHost\Listener -Transport HTTPS -Address * -CertificateThumbPrint (Get-ChildItem -Path Cert:\LocalMachine\My | Where-Object {$_.Subject -eq "CN=servername"}).Thumbprint

启用SSH PowerShell（备选）

# Install OpenSSH Server
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

# Start and enable SSH
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'

# Configure firewall
New-NetFirewallRule -Name sshd -DisplayName 'OpenSSH Server (sshd)' -Enabled True -Direction Inbound -Protocol TCP -Action Allow -LocalPort 22

故障排除

连接问题

WinRM错误:
- 启用WinRM： winrm quickconfig
- 设置受信任的主机： Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*"
- 检查端口5985/5986的防火墙规则
- 验证WinRM服务是否正在运行： Get-Service WinRM
SSH错误:
- 检查SSH服务： Get-Service sshd
- 验证端口22是否打开： Test-NetConnection -Port 22
- 检查SSH配置： C:\ProgramData\ssh\sshd_config
身份验证错误:
- 验证凭据是否正确
- 检查用户是否具有远程管理权限
- 对于域帐户，请使用以下格式： DOMAIN\username

工具未出现

验证Docker镜像构建成功
检查目录和注册表文件
确保Claude Desktop配置包括自定义目录
重新启动克劳德桌面

性能问题

检查Docker和目标服务器之间的网络连接
验证WinRM/SSH超时设置
监控操作期间的服务器资源使用情况

发展

添加新工具

将该功能添加到 windows_admin_server.py
用…装饰 @mcp.tool()
用新的工具名称更新目录条目
重建Docker镜像

局部测试

# Set environment variables for testing
export WINDOWS_ADMIN_LOG_DIR="./logs"

# Run directly
python windows_admin_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python windows_admin_server.py

# Test WinRM connection
python -c "from winrm import Session; s = Session('http://server:5985/wsman', auth=('user', 'pass')); print(s.run_ps('hostname').std_out)"

依赖项

mcp[cli] -MCP服务器框架
pywinrm -Windows远程管理库
requests-ntlm -WinRM的NTLM身份验证
asyncssh -用于回退的异步SSH库
aiofiles -异步文件操作
httpx -HTTP客户端库

许可证

MIT许可证

更新日志

2.0.0版本（最新）

突破性变化：将模拟RDP替换为实际WinRM连接
新：添加了SSH PowerShell回退支持
新：自动协议选择（WinRM→ SSH)
改进的：真正的连接测试而不是模拟
增强：更好的错误处理和日志记录

版本1.0.0

具有模拟RDP功能的初始版本