claude-mcp-windows-guide

Troubleshooting Guide: Claude Desktop MCP-GitHub Integration on Windows

This guide documents the process of setting up and troubleshooting MCP-GitHub integration for Claude Desktop on Windows platform.

Prerequisites

• Windows operating system
• Node.js and npm installed
• Claude Desktop application
• GitHub account with access token

Common Issues and Solutions

1. Installation of MCP-GitHub Server

First, install the MCP-GitHub server globally:

npm install -g @modelcontextprotocol/server-github

Verify the installation:

npx @modelcontextprotocol/server-github --version

Expected output: "GitHub MCP Server running on stdio"

2. GitHub Token Setup

1. Go to GitHub Settings -> Developer Settings -> Personal Access Tokens
2. Choose "Tokens (classic)" (not Fine-grained tokens)
3. Required permissions:
   • repo (minimum requirement)
   • Additional permissions based on your needs

3. Configuration File Location and Setup

Important Note About Installation Paths

The configuration file location may vary depending on your installation. Common paths include:

C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json
# or
C:\Users\[YourUsername]\AppData\Local\AnthropicClaude\claude_desktop_config.json

To find your correct path:

1. Check both locations above
2. Create the configuration file in the directory that exists on your system
3. If both exist, try configuring in each location until successful

Configuration File Content

Official Configuration (using npx)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-github"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
      }
    }
  }
}

Alternative Working Configuration (using node)

If the official configuration doesn't work, try this alternative configuration that uses the direct node path:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": [
        "C:/Users/[YourUsername]/AppData/Roaming/npm/node_modules/@modelcontextprotocol/server-github/dist/index.js",
        "--debug"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token"
      }
    }
  }
}

Important notes:

• The file MUST be named claude_desktop_config.json
• Different installation methods may use different config file locations
• Use forward slashes (/) in the path, not backslashes (\)
• Ensure proper JSON formatting with double quotes
• Replace [YourUsername] with your actual Windows username
• Replace your-github-token with your actual GitHub token

4. Common Errors and Solutions

Configuration File Not Found

• Check both possible installation paths mentioned above
• Ensure you're creating the config file in the correct location
• Verify the file name is exactly claude_desktop_config.json

Invalid Character Error

If you see a Windows Script Host error about invalid characters:

• Check path separators (use / instead of \)
• Ensure no escape characters in the path
• Try switching between the npx and node configurations

JSON Syntax Error

If you see "Could not load app settings":

• Verify JSON syntax
• Check for proper double quotes
• Ensure no trailing commas
• Validate JSON format using a JSON validator
• Confirm the file is named exactly as claude_desktop_config.json

Connection Issues

If the server isn't connecting:

• Verify the token is properly set
• Check if the MCP server is running (npx @modelcontextprotocol/server-github --version)
• If the npx configuration doesn't work, try the node configuration with full path
• Ensure the path to the server module is correct
• Try creating the config file in the alternate location if one method doesn't work

Verification Process

1. Close Claude Desktop completely
2. Reopen the application
3. Check for successful connection
4. If issues persist, add --debug flag in the args array for more detailed logs

Additional Tips

• Always use proper JSON formatting
• Double-check paths and usernames
• Ensure all directories exist
• Keep your GitHub token secure
• Consider using environment variables for sensitive information
• If the official npx configuration doesn't work, try the alternative node configuration
• Pay attention to the installation path differences and try both possible locations

Contributing

If you've encountered and solved other issues, please feel free to contribute to this guide.

Support

If you need additional help:

• Check Claude Desktop documentation
• Visit the GitHub repository
• Contact support for persistent issues