windows-admin-mcp

Cosmicjedi/windows-admin-mcp

3.3

If you are the rightful owner of windows-admin-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server designed for remote Windows server administration and troubleshooting using RDP and PowerShell.

Tools
8
Resources
0
Prompts
0

Windows Admin MCP Server

A Model Context Protocol (MCP) server that provides remote Windows server administration and troubleshooting capabilities via WinRM and SSH PowerShell protocols.

Purpose

This MCP server provides a secure interface for AI assistants to remotely connect to Windows servers, diagnose issues, and apply solutions using PowerShell commands through WinRM (primary) or SSH (fallback) protocols.

Features

Remote Connection Methods

  • WinRM (Primary) - Windows Remote Management protocol for native Windows remote administration

    • Supports both HTTP (port 5985) and HTTPS (port 5986)
    • NTLM and Basic authentication
    • Native PowerShell command execution

  • SSH PowerShell (Fallback) - SSH-based PowerShell execution for servers with OpenSSH

    • Works with Windows 10/Server 2019+ built-in OpenSSH
    • Automatic fallback when WinRM is unavailable
    • Full PowerShell command support

Available Tools

  • test_connection - Test connectivity to a Windows server using ping, WinRM, and SSH port checks
  • diagnose_system - Gather comprehensive system information to diagnose issues
  • execute_command - Execute PowerShell or CMD commands on the remote server
  • check_service - Check Windows service status and provide management options
  • troubleshoot_application - Troubleshoot specific applications that are crashing or not working
  • apply_solution - Apply PowerShell solution scripts to fix identified issues
  • get_performance_metrics - Get current CPU, memory, disk, and network metrics
  • view_logs - View troubleshooting logs for specific servers and dates

Prerequisites

Docker Environment

  • Docker Desktop with MCP Toolkit enabled
  • Docker MCP CLI plugin (docker mcp command)

Target Windows Servers

For WinRM access (recommended):

  • WinRM enabled and configured (winrm quickconfig)
  • PowerShell remoting enabled (Enable-PSRemoting)
  • Firewall rules for WinRM (ports 5985/5986)
  • Network connectivity from Docker container

For SSH fallback (optional):

  • OpenSSH Server installed and running
  • SSH port 22 open in firewall
  • PowerShell available via SSH

Installation

Step 1: Clone the Repository

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

Step 2: Build Docker Image

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

Step 3: Set Up Log Directory (Optional)

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

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

Step 4: Create Custom Catalog

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

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

Add this entry to 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

Step 5: Update Registry

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

Add this entry under the existing registry: key:

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

Step 6: Configure Claude Desktop

Find your Claude Desktop config file:

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

Edit the file and add your custom catalog:

{
  "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"
      ]
    }
  }
}

Step 7: Restart Claude Desktop

  1. Quit Claude Desktop completely
  2. Start Claude Desktop again
  3. Your Windows Admin tools should appear!

Usage Examples

In Claude Desktop, you can ask:

  • "Test connection to Windows server 192.168.1.100 with username Administrator and password"
  • "Diagnose why the 'Flying Doghouse' application is crashing on server SNOOPY"
  • "Check the status of the Windows Update service on server PROD-WEB-01"
  • "Get performance metrics from server DB-SERVER-02 using credentials admin/password"
  • "Execute Get-Process command on server APP-SERVER with my credentials"
  • "Troubleshoot why IIS is not starting on WEB-SERVER-01"
  • "Apply a solution to restart the Print Spooler service on PRINT-SERVER"
  • "Show me the logs for server SNOOPY from today"
  • "Find the test.log file in C:\Users\Administrator and read its contents"

Architecture

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

Connection Flow

  1. Primary Method: WinRM

    • Attempts HTTP connection on port 5985
    • Falls back to HTTPS on port 5986 if HTTP fails
    • Uses NTLM authentication by default, falls back to Basic

  2. Fallback Method: SSH PowerShell

    • Connects via SSH on port 22
    • Executes PowerShell commands through SSH session
    • Works with Windows OpenSSH Server

Log Management

The server automatically creates daily log files for each server:

  • Format: {hostname}-{MMDDYYYY}.log
  • Location: Configurable via WINDOWS_ADMIN_LOG_DIR environment variable
  • Default: /app/logs in the container
  • Contains timestamped entries of all operations performed

Security Considerations

  • Credentials are passed in real-time and not stored
  • WinRM connections use NTLM/Basic authentication
  • SSH connections use password authentication
  • Log files contain operation history but no passwords
  • Running as non-root user in Docker container
  • Consider using HTTPS WinRM (port 5986) for production
  • Implement credential management integration with your secret server

Windows Server Configuration

Enable WinRM (Recommended)

# 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

Enable SSH PowerShell (Alternative)

# 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

Troubleshooting

Connection Issues

  1. WinRM Errors:

    • Enable WinRM: winrm quickconfig
    • Set trusted hosts: Set-Item WSMan:\localhost\Client\TrustedHosts -Value "*"
    • Check firewall rules for ports 5985/5986
    • Verify WinRM service is running: Get-Service WinRM

  2. SSH Errors:

    • Check SSH service: Get-Service sshd
    • Verify port 22 is open: Test-NetConnection -Port 22
    • Check SSH configuration: C:\ProgramData\ssh\sshd_config

  3. Authentication Errors:

    • Verify credentials are correct
    • Check if user has remote management permissions
    • For domain accounts, use format: DOMAIN\username

Tools Not Appearing

  • Verify Docker image built successfully
  • Check catalog and registry files
  • Ensure Claude Desktop config includes custom catalog
  • Restart Claude Desktop

Performance Issues

  • Check network connectivity between Docker and target servers
  • Verify WinRM/SSH timeout settings
  • Monitor server resource usage during operations

Development

Adding New Tools

  1. Add the function to windows_admin_server.py
  2. Decorate with @mcp.tool()
  3. Update the catalog entry with the new tool name
  4. Rebuild the Docker image

Local Testing

# 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)"

Dependencies

  • mcp[cli] - MCP server framework
  • pywinrm - Windows Remote Management library
  • requests-ntlm - NTLM authentication for WinRM
  • asyncssh - Asynchronous SSH library for fallback
  • aiofiles - Asynchronous file operations
  • httpx - HTTP client library

License

MIT License

Changelog

Version 2.0.0 (Latest)

  • Breaking Change: Replaced simulated RDP with actual WinRM connections
  • New: Added SSH PowerShell fallback support
  • New: Automatic protocol selection (WinRM → SSH)
  • Improved: Real connectivity testing instead of simulation
  • Enhanced: Better error handling and logging

Version 1.0.0

  • Initial release with simulated RDP functionality