MCP Server Management

MCP Server Management

Status: Production Ready Last Updated: 2025-12-06 Dependencies: Node.js 18+, Claude Desktop, winadmin-powershell skill Latest Versions: Claude Desktop 0.7.x, Node.js 22.x

Quick Start (10 Minutes)

1. Verify Prerequisites

# Check Node.js (required for most MCP servers)
node --version   # Should be 18+

# Check npm
npm --version

# Verify Claude Desktop installed
Test-Path "$env:APPDATA\Claude\claude_desktop_config.json"

2. Locate Config File

# Claude Desktop config location
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"

# Read current config
Get-Content $configPath | ConvertFrom-Json | ConvertTo-Json -Depth 10

3. Install Your First MCP Server

# Example: Install filesystem MCP server
npm install -g @modelcontextprotocol/server-filesystem

# Add to Claude Desktop config (see Configuration section)

Critical Rules

Always Do

• Backup claude_desktop_config.json before editing
• Use absolute paths for all executables and arguments
• Restart Claude Desktop after config changes
• Test MCP servers in isolation before adding to config
• Log all MCP installations to your registry

Never Do

• Use relative paths in MCP server configurations
• Edit config while Claude Desktop is running (can corrupt)
• Install MCP servers without verifying Node.js compatibility
• Mix npx and global npm installations for same server
• Forget to escape backslashes in JSON (\\ not \)

Claude Desktop Configuration

Config File Location

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

PowerShell:

$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"

Config File Structure

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["path/to/server.js"],
      "env": {
        "ENV_VAR": "value"
      },
      "disabled": false
    }
  }
}

Configuration Fields

MCP Server Installation Patterns

Pattern 1: NPX (Recommended for Quick Setup)

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:/Users/Owner/Documents"
      ]
    }
  }
}

Pros: Always uses latest version, no global install needed Cons: Slower startup, requires internet on first run

Pattern 2: Global NPM Install

# Install globally
npm install -g @modelcontextprotocol/server-filesystem

{
  "mcpServers": {
    "filesystem": {
      "command": "node",
      "args": [
        "C:/Users/Owner/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-filesystem/dist/index.js",
        "C:/Users/Owner/Documents"
      ]
    }
  }
}

Pros: Faster startup, works offline Cons: Manual updates needed

Pattern 3: Local Clone (For Development/Customization)

# Clone to MCP directory
cd D:/mcp
git clone https://github.com/org/mcp-server-name.git
cd mcp-server-name
npm install
npm run build

{
  "mcpServers": {
    "server-name": {
      "command": "node",
      "args": ["D:/mcp/mcp-server-name/dist/index.js"]
    }
  }
}

Pros: Full control, can modify source Cons: Manual updates, more disk space

Pattern 4: Python MCP Server

{
  "mcpServers": {
    "python-server": {
      "command": "python",
      "args": ["-m", "mcp_server_package"],
      "env": {
        "PYTHONPATH": "D:/path/to/server"
      }
    }
  }
}

The Three MCP CLI Tools

Windows systems commonly use three MCP servers for CLI operations:

1. Desktop Commander (Primary for Local Work)

Package: @anthropic-ai/desktop-commander Best For: File operations, code editing, persistent sessions

{
  "mcpServers": {
    "desktop-commander": {
      "command": "npx",
      "args": ["-y", "@anthropic-ai/desktop-commander"]
    }
  }
}

Tools Provided:

• read_file - Read file contents
• write_file - Write/create files
• edit_block - Surgical code edits with diff
• list_directory - List directory contents
• search_files - Search for files by pattern
• get_file_info - File metadata
• start_process - Start persistent process
• interact_with_process - Send input to process
• read_process_output - Get process output
• get_config / set_config_value - Configure server

Key Features:

• Persistent process sessions (maintains state)
• Better PATH handling
• Diff-based code editing
• Interactive REPL support

2. Win-CLI (SSH and Multi-Shell)

Best For: SSH operations, remote servers, multiple shell types

{
  "mcpServers": {
    "win-cli": {
      "command": "node",
      "args": [
        "D:/mcp/win-cli-mcp-server/dist/index.js",
        "--config",
        "D:/mcp/win-cli-mcp-server/config.json"
      ]
    }
  }
}

Tools Provided:

• execute_command - Run shell command
• ssh_execute - Run command on remote server
• ssh_connect - Connect to SSH server
• list_ssh_connections - List configured SSH connections

Key Features:

• Multiple shell support (PowerShell, CMD, Git Bash)
• Pre-configured SSH connections
• Isolated shell sessions

Win-CLI Config (config.json):

{
  "shells": {
    "powershell": {
      "enabled": true,
      "command": "C:\\Program Files\\PowerShell\\7\\pwsh.exe",
      "args": ["-Command"]
    },
    "cmd": {
      "enabled": true,
      "command": "cmd.exe",
      "args": ["/c"]
    }
  },
  "ssh": {
    "connections": [
      {
        "id": "server-1",
        "host": "192.168.1.100",
        "username": "admin",
        "privateKeyPath": "C:/Users/Owner/.ssh/id_rsa"
      }
    ]
  },
  "security": {
    "allowedPaths": ["D:/", "C:/Users/Owner"],
    "blockedCommands": ["format", "shutdown", "rm -rf /"],
    "commandTimeout": 60
  }
}

3. Claude Code MCP (Complex Multi-File Tasks)

Package: @anthropic-ai/claude-code-mcp Best For: Complex refactoring, git workflows, multi-file edits

{
  "mcpServers": {
    "claude-code-mcp": {
      "command": "node",
      "args": ["D:/mcp/claude-code-mcp/dist/index.js"],
      "env": {
        "CLAUDE_CLI_PATH": "C:/Users/Owner/AppData/Roaming/npm/claude.cmd"
      }
    }
  }
}

Tools Provided:

• claude_code - Execute Claude Code CLI with prompt

Key Features:

• Wraps official Claude Code CLI
• Auto-bypasses permissions for automation
• Best for complex multi-file operations

When to Use:

// Complex refactoring
claude_code({
  prompt: "Refactor all API calls to use async/await",
  workFolder: "D:/project"
})

// Git workflows
claude_code({
  prompt: "Stage changes, commit with message, push to develop",
  workFolder: "D:/project"
})

Tool Selection Guide

MCP Installation Workflow

Step-by-Step Process

# 1. Check if server exists in registry (if using registry)
$registry = Get-Content $env:MCP_REGISTRY | ConvertFrom-Json
$registry.mcpServers.'server-name'

# 2. Backup current config
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"
Copy-Item $configPath "$configPath.backup.$(Get-Date -Format 'yyyyMMdd-HHmmss')"

# 3. Install server (choose method)
# Option A: NPX (no install needed)
# Option B: Global npm
npm install -g @org/mcp-server-name
# Option C: Local clone
cd D:/mcp && git clone https://github.com/org/mcp-server.git

# 4. Read current config
$config = Get-Content $configPath | ConvertFrom-Json

# 5. Add server to config
$config.mcpServers | Add-Member -NotePropertyName "server-name" -NotePropertyValue @{
    command = "node"
    args = @("D:/mcp/mcp-server/dist/index.js")
}

# 6. Save config
$config | ConvertTo-Json -Depth 10 | Set-Content $configPath

# 7. Update registry (if using)
# Add entry to mcp-registry.json

# 8. Log installation
Log-Operation -Status "SUCCESS" -Operation "MCP Install" -Details "Installed server-name" -LogType "installation"

# 9. Restart Claude Desktop
Stop-Process -Name "Claude" -ErrorAction SilentlyContinue
Start-Process "$env:LOCALAPPDATA\Programs\Claude\Claude.exe"

# 10. Test server
# Open Claude Desktop and verify server tools are available

MCP Registry Pattern

Maintain a central registry of installed MCP servers:

Registry Schema

{
  "lastUpdated": "2025-12-06T12:00:00Z",
  "mcpServers": {
    "desktop-commander": {
      "installed": true,
      "installDate": "2025-10-01",
      "installMethod": "npx",
      "version": "latest",
      "purpose": "File operations and persistent sessions",
      "configPath": null,
      "notes": "Primary tool for local file operations"
    },
    "win-cli": {
      "installed": true,
      "installDate": "2025-10-01",
      "installMethod": "local-clone",
      "version": "1.0.0",
      "purpose": "SSH and multi-shell support",
      "configPath": "D:/mcp/win-cli-mcp-server/config.json",
      "notes": "Deprecated upstream, using local fork"
    },
    "filesystem": {
      "installed": true,
      "installDate": "2025-10-15",
      "installMethod": "npm-global",
      "version": "0.6.2",
      "purpose": "Filesystem access for specific directories",
      "configPath": null,
      "notes": "Limited to Documents folder"
    }
  }
}

Registry Update Script

function Update-McpRegistry {
    param(
        [string]$ServerName,
        [string]$InstallMethod,
        [string]$Version,
        [string]$Purpose,
        [string]$ConfigPath,
        [string]$Notes
    )

    $registryPath = $env:MCP_REGISTRY
    $registry = Get-Content $registryPath | ConvertFrom-Json

    $entry = @{
        installed = $true
        installDate = (Get-Date -Format "yyyy-MM-dd")
        installMethod = $InstallMethod
        version = $Version
        purpose = $Purpose
        configPath = $ConfigPath
        notes = $Notes
    }

    if ($registry.mcpServers.PSObject.Properties.Name -contains $ServerName) {
        $registry.mcpServers.$ServerName = $entry
    } else {
        $registry.mcpServers | Add-Member -NotePropertyName $ServerName -NotePropertyValue $entry
    }

    $registry.lastUpdated = (Get-Date -Format "yyyy-MM-ddTHH:mm:ssZ")
    $registry | ConvertTo-Json -Depth 10 | Set-Content $registryPath

    Write-Host "Updated registry: $ServerName" -ForegroundColor Green
}

Common MCP Servers

Official Anthropic Servers

Community Servers

Comprehensive Diagnostics

When MCP servers fail, collect comprehensive diagnostic information using the bundled script:

Run Full Diagnostics

# Full system diagnostic
.\scripts\diagnose-mcp.ps1

# Diagnose specific server
.\scripts\diagnose-mcp.ps1 -ServerName "desktop-commander"

# Save report to file
.\scripts\diagnose-mcp.ps1 -OutputFile "mcp-report.md"

# JSON output for automation
.\scripts\diagnose-mcp.ps1 -Json -OutputFile "mcp-report.json"

What the Diagnostic Collects

Manual Information Collection

If the script isn't available, collect this information manually:

1. System Environment

# PowerShell version
$PSVersionTable | Format-List

# Node.js
node --version
(Get-Command node).Source

# npm
npm --version
npm root -g

2. Claude Desktop Config

# Config location and content
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"
Test-Path $configPath
Get-Content $configPath | ConvertFrom-Json | ConvertTo-Json -Depth 10

3. PATH Analysis

# Check for npm in PATH
$env:PATH -split ';' | Where-Object { $_ -like "*npm*" -or $_ -like "*node*" }

# User PATH (registry)
[Environment]::GetEnvironmentVariable('PATH', 'User') -split ';'

4. Test Server Manually

# For npx servers
npx.cmd -y @modelcontextprotocol/server-filesystem --help

# For local servers
node "D:/mcp/server-name/dist/index.js" --help

5. Check Claude Logs

# Find logs
Get-ChildItem "$env:APPDATA\Claude\logs" -Recurse

# View recent log
Get-Content "$env:APPDATA\Claude\logs\main.log" -Tail 50

# Search for MCP errors
Select-String -Path "$env:APPDATA\Claude\logs\*.log" -Pattern "mcp|MCP|error|ENOENT"

6. Process Information

# Claude Desktop process
Get-Process -Name "Claude" | Format-List *

# All Node processes (potential MCP servers)
Get-Process -Name "node" | ForEach-Object {
    $cmdLine = (Get-CimInstance Win32_Process -Filter "ProcessId = $($_.Id)").CommandLine
    [PSCustomObject]@{
        PID = $_.Id
        Memory = [math]::Round($_.WorkingSet64 / 1MB, 2)
        CommandLine = $cmdLine
    }
} | Format-Table -AutoSize

7. Verify File Paths

# Check all paths referenced in config
$config = Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json

foreach ($server in $config.mcpServers.PSObject.Properties) {
    Write-Host "`n=== $($server.Name) ===" -ForegroundColor Cyan

    # Check command
    $cmd = $server.Value.command
    Write-Host "Command: $cmd"
    Write-Host "  Exists: $(Test-Path $cmd -ErrorAction SilentlyContinue)"

    # Check args that look like paths
    foreach ($arg in $server.Value.args) {
        if ($arg -match '^[A-Za-z]:' -or $arg -match '\.(js|mjs|ts)$') {
            Write-Host "Arg: $arg"
            Write-Host "  Exists: $(Test-Path $arg)"
        }
    }
}

Information to Include in Bug Reports

When reporting MCP issues, include:

1. Diagnostic report from diagnose-mcp.ps1
2. Exact error message from Claude Desktop or logs
3. Server configuration (redact API keys)
4. Steps to reproduce
5. What you've already tried

Troubleshooting

Problem: MCP server not starting

Symptoms: Server shows as disabled or tools not available

Diagnostic Steps:

# 1. Check config syntax
$config = Get-Content "$env:APPDATA\Claude\claude_desktop_config.json" | ConvertFrom-Json
$config.mcpServers.'server-name'

# 2. Test command manually
node "D:/mcp/server/dist/index.js"

# 3. Check Node.js version
node --version  # Should be 18+

# 4. Check for missing dependencies
cd D:/mcp/server && npm install

Common Fixes:

• Ensure command path exists: Test-Path "C:/path/to/node.exe"
• Use forward slashes or escaped backslashes: D:/mcp or D:\\mcp
• Restart Claude Desktop completely (check Task Manager)

Problem: "spawn ENOENT" error

Cause: Command executable not found

Fix:

# Use absolute path to node
$nodePath = (Get-Command node).Source
Write-Host "Use this path: $nodePath"
# Example: C:\Program Files\nodejs\node.exe

Problem: Environment variables not available

Cause: env block not properly formatted

Fix:

{
  "mcpServers": {
    "server": {
      "command": "node",
      "args": ["server.js"],
      "env": {
        "API_KEY": "your-key-here",
        "DEBUG": "true"
      }
    }
  }
}

Problem: Server works in terminal but not in Claude

Cause: Different PATH/environment in Claude vs terminal

Fix: Use absolute paths for everything:

{
  "command": "C:/Program Files/nodejs/node.exe",
  "args": ["C:/Users/Owner/AppData/Roaming/npm/node_modules/@org/server/dist/index.js"]
}

Problem: Config file corrupted

Recovery:

# Restore from backup
$configPath = "$env:APPDATA\Claude\claude_desktop_config.json"
$backups = Get-ChildItem "$env:APPDATA\Claude\*.backup.*" | Sort-Object LastWriteTime -Descending
Copy-Item $backups[0].FullName $configPath

# Or create minimal config
@{
    mcpServers = @{}
} | ConvertTo-Json | Set-Content $configPath

Known Issues Prevention

Issue #1: Path escaping in JSON

Error: Invalid JSON syntax Prevention: Use forward slashes D:/mcp or double backslashes D:\\mcp

Issue #2: npx.cmd vs npx on Windows

Error: spawn npx ENOENT Prevention: Use npx.cmd on Windows:

{
  "command": "npx.cmd",
  "args": ["-y", "@package/name"]
}

Issue #3: Node version mismatch

Error: Unexpected token, SyntaxError Prevention: Verify Node 18+ is in PATH and used by Claude

Issue #4: Config edited while Claude running

Error: Config resets or corrupts Prevention: Always close Claude Desktop before editing config

Issue #5: Missing build step for cloned repos

Error: Cannot find module './dist/index.js' Prevention: Always run npm install && npm run build after cloning

Using Bundled Resources

Scripts (scripts/)

add-mcp-server.ps1 - Add server to Claude Desktop config

.\scripts\add-mcp-server.ps1 -Name "server-name" -Command "node" -Args @("path/to/server.js")

backup-config.ps1 - Backup Claude Desktop config

.\scripts\backup-config.ps1

Templates (templates/)

claude-desktop-config.json - Example config structure mcp-registry.json - Registry template win-cli-config.json - Win-CLI configuration template

Complete Setup Checklist

• Node.js 18+ installed and in PATH
• Claude Desktop installed
• Config file exists at %APPDATA%\Claude\claude_desktop_config.json
• Config file backed up
• MCP server installed (npx, npm, or clone)
• Server added to config with absolute paths
• Claude Desktop restarted
• Server tools visible in Claude
• Registry updated (if using)
• Installation logged

Official Documentation

• MCP Protocol: https://modelcontextprotocol.io/
• MCP Servers: https://github.com/modelcontextprotocol/servers
• Claude Desktop: https://claude.ai/download
• Desktop Commander: https://github.com/anthropics/desktop-commander

Package Versions (Verified 2025-12-06)

{
  "dependencies": {
    "node": ">=18.0.0",
    "@modelcontextprotocol/server-filesystem": "^0.6.x",
    "@anthropic-ai/desktop-commander": "^0.1.x"
  }
}