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功能的初始版本