windows管理服务器-mcp

Name: windows管理服务器-mcp
Author: Cosmicjedi

作者：Cosmicjedi3 星标更新：2025-09-25

安装使用来源：spider==github.com

项目介绍

Windows Admin MCP Server

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

目的

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

特性

远程连接方法

WinRM（主要） - Windows远程管理协议，用于原生Windows远程管理
- 支持HTTP（端口5985）和HTTPS（端口5986）
- NTLM和基本身份验证
- 原生PowerShell命令执行
SSH PowerShell（备用） - 基于SSH的PowerShell执行，适用于安装了OpenSSH的服务器
- 兼容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 Desktop
Docker MCP CLI插件 (docker mcp命令)

目标Windows服务器

对于WinRM访问（推荐）：

启用并配置WinRM (winrm quickconfig)
启用PowerShell远程管理 (Enable-PSRemoting)
WinRM防火墙规则（端口5985/5986）
Docker容器到目标服务器的网络连通性

对于SSH备用（可选）：

安装并运行OpenSSH服务器
防火墙中打开SSH端口22
通过SSH可用的PowerShell

安装

第一步：克隆仓库

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

第二步：构建Docker镜像

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

第三步：设置日志目录（可选）

# 创建本地日志目录
mkdir -p ~/windows-admin-logs

# 设置为环境变量
export WINDOWS_ADMIN_LOG_DIR=~/windows-admin-logs

第四步：创建自定义目录

# 如果不存在，则创建目录
mkdir -p ~/.docker/mcp/catalogs

# 创建或编辑custom.yaml
nano ~/.docker/mcp/catalogs/custom.yaml

在custom.yaml中添加以下条目：

version: 2
name: custom
displayName: 自定义MCP服务器
registry:
  windows-admin:
    description: "通过WinRM和SSH进行远程Windows服务器管理"
    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: 监控
      tags:
        - windows
        - administration
        - troubleshooting
        - powershell
        - winrm
        - ssh
        - remote
      license: MIT
      owner: local

第五步：更新注册表

# 编辑注册表文件
nano ~/.docker/mcp/registry.yaml

在现有的registry:键下添加以下条目：

registry:
  # ... 已有的服务器 ...
  windows-admin:
    ref: ""

第六步：配置Claude Desktop

找到你的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %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"
      ]
    }
  }
}

第七步：重启Claude Desktop

完全退出Claude Desktop
再次启动Claude Desktop
你的Windows管理工具应该会出现！

使用示例

在Claude Desktop中，你可以询问：

"测试与IP地址为192.168.1.100的Windows服务器的连接，用户名为Administrator，密码为..."
"诊断为什么'Flying Doghouse'应用程序在服务器SNOOPY上崩溃"
"检查服务器PROD-WEB-01上的Windows Update服务状态"
"获取服务器DB-SERVER-02的性能指标，使用凭证admin/password"
"使用我的凭证在服务器APP-SERVER上执行Get-Process命令"
"故障排查为什么WEB-SERVER-01上的IIS无法启动"
"应用解决方案以重启PRINT-SERVER上的打印后台处理程序服务"
"显示服务器SNOOPY今天的日志"
"查找C:\Users\Administrator中的test.log文件并读取其内容"

架构

Claude Desktop → MCP网关 → Windows Admin MCP服务器
                                         ↓
                                    [WinRM/SSH]
                                         ↓
                                  Windows服务器
                                         ↓
                                   本地日志文件
                            (/app/logs/hostname-MMDDYYYY.log)

连接流程

主要方法：WinRM
- 尝试在端口5985上建立HTTP连接
- 如果HTTP失败，则切换到端口5986上的HTTPS
- 默认使用NTLM身份验证，如果失败则切换到基本身份验证
备用方法：SSH PowerShell
- 通过端口22连接SSH
- 通过SSH会话执行PowerShell命令
- 兼容Windows OpenSSH服务器

日志管理

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

格式：{hostname}-{MMDDYYYY}.log
位置：可通过WINDOWS_ADMIN_LOG_DIR环境变量配置
默认：容器内的/app/logs
包含所有操作的时间戳记录

安全注意事项

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

Windows服务器配置

启用WinRM（推荐）

# 快速配置
winrm quickconfig

# 或手动配置
Enable-PSRemoting -Force
Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*"
Set-Service WinRM -StartupType Automatic
Start-Service WinRM

# 对于HTTPS（更安全）
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（替代方案）

# 安装OpenSSH服务器
Add-WindowsCapability -Online -Name OpenSSH.Server~~~~0.0.1.0

# 启动并启用SSH
Start-Service sshd
Set-Service -Name sshd -StartupType 'Automatic'

# 配置防火墙
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配置包括自定义目录
重启Claude Desktop

性能问题

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

开发

添加新工具

在windows_admin_server.py中添加函数
使用@mcp.tool()装饰器
更新目录条目，添加新的工具名称
重新构建Docker镜像

本地测试

# 设置测试环境变量
export WINDOWS_ADMIN_LOG_DIR="./logs"

# 直接运行
python windows_admin_server.py

# 测试MCP协议
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python windows_admin_server.py

# 测试WinRM连接
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（最新）

重大变更：用实际的WinRM连接替换了模拟的RDP
新增：增加了SSH PowerShell备用支持
新增：自动协议选择（WinRM → SSH）
改进：使用真实连接测试代替模拟
增强：更好的错误处理和日志记录

版本1.0.0

初始发布，带有模拟的RDP功能