Content
# 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:
```bash
npm install -g @modelcontextprotocol/server-github
```
Verify the installation:
```bash
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)
```json
{
"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:
```json
{
"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
