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

| Field | Required | Description | |-------|----------|-------------| | command | Yes | Executable to run (node, npx, python, etc.) | | args | Yes | Array of arguments passed to command | | env | No | Environment variables for the server | | disabled | No | Set true to disable without removing |

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

| Task | Recommended Tool | Reason | |------|-----------------|--------| | Read/write files | Desktop Commander | Native file tools | | Edit code blocks | Desktop Commander | Diff-based editing | | Run local commands | Desktop Commander | Better PATH handling | | SSH to remote server | Win-CLI | SSH support | | Use specific shell | Win-CLI | Multi-shell support | | Complex refactoring | Claude Code MCP | Multi-file awareness | | Git operations | Claude Code MCP | Git workflow support | | Interactive REPL | Desktop Commander | Persistent sessions |

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

| Server | Package | Purpose | |--------|---------|---------| | Filesystem | @modelcontextprotocol/server-filesystem | File system access | | GitHub | @modelcontextprotocol/server-github | GitHub API integration | | GitLab | @modelcontextprotocol/server-gitlab | GitLab API integration | | Slack | @modelcontextprotocol/server-slack | Slack integration | | Google Drive | @modelcontextprotocol/server-gdrive | Google Drive access | | PostgreSQL | @modelcontextprotocol/server-postgres | Database queries | | SQLite | @modelcontextprotocol/server-sqlite | SQLite database | | Puppeteer | @modelcontextprotocol/server-puppeteer | Browser automation | | Brave Search | @modelcontextprotocol/server-brave-search | Web search | | Fetch | @modelcontextprotocol/server-fetch | HTTP requests | | Memory | @modelcontextprotocol/server-memory | Persistent memory | | Sequential Thinking | @modelcontextprotocol/server-sequential-thinking | Step-by-step reasoning |

Community Servers

| Server | Package/Repo | Purpose | |--------|--------------|---------| | Desktop Commander | @anthropic-ai/desktop-commander | File ops + terminals | | Context7 | context7-mcp | Library documentation | | Obsidian | Various | Note integration | | Notion | Various | Notion integration |

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

| Category | Information | |----------|-------------| | System | OS version, PowerShell version, user context | | Node.js | Version, path, npm path, global modules location | | PATH | User PATH, session PATH, npm presence | | Config | File location, validity, all configured servers | | Server Details | Command, args, env vars, file existence checks | | MCP Directory | Local clones, build status, node_modules presence | | Processes | Claude Desktop status, running Node processes | | Logs | Claude Desktop log location, recent entries, MCP errors | | Issues | Automated detection with recommended fixes |

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:

Diagnostic report from diagnose-mcp.ps1
Exact error message from Claude Desktop or logs
Server configuration (redact API keys)
Steps to reproduce
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"
  }
}

mcp-server-management

MCP Server Management

Quick Start (10 Minutes)

1. Verify Prerequisites

2. Locate Config File

3. Install Your First MCP Server

Critical Rules

Always Do

Never Do

Claude Desktop Configuration

Config File Location

Config File Structure

Configuration Fields

MCP Server Installation Patterns

Pattern 1: NPX (Recommended for Quick Setup)

Pattern 2: Global NPM Install

Pattern 3: Local Clone (For Development/Customization)

Pattern 4: Python MCP Server

The Three MCP CLI Tools

1. Desktop Commander (Primary for Local Work)

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

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

Tool Selection Guide

MCP Installation Workflow

Step-by-Step Process

MCP Registry Pattern

Registry Schema

Registry Update Script

Common MCP Servers

Official Anthropic Servers

Community Servers

Comprehensive Diagnostics

Run Full Diagnostics

What the Diagnostic Collects

Manual Information Collection

1. System Environment

2. Claude Desktop Config

3. PATH Analysis

4. Test Server Manually

5. Check Claude Logs

6. Process Information

7. Verify File Paths

Information to Include in Bug Reports

Troubleshooting

Problem: MCP server not starting

Problem: "spawn ENOENT" error

Problem: Environment variables not available

Problem: Server works in terminal but not in Claude

Problem: Config file corrupted

Known Issues Prevention

Issue #1: Path escaping in JSON

Issue #2: npx.cmd vs npx on Windows

Issue #3: Node version mismatch

Issue #4: Config edited while Claude running

Issue #5: Missing build step for cloned repos

Using Bundled Resources

Scripts (scripts/)

Templates (templates/)

Complete Setup Checklist

Official Documentation

Package Versions (Verified 2025-12-06)