GitHub MCP Server Setup Guide

This guide provides step-by-step instructions for setting up the GitHub MCP (Model Context Protocol) server with Claude Desktop, enabling seamless integration between Claude and your GitHub repositories.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that enables AI assistants to securely connect to local and remote resources. The GitHub MCP server allows Claude Desktop to interact with GitHub repositories, enabling features like reading files, creating repositories, managing issues, and more.

Prerequisites

Before starting, ensure you have:

• Claude Desktop installed on your computer
• Node.js (version 16 or higher) installed
• A GitHub account
• Git installed on your system

Step 1: Install the GitHub MCP Server

1. Open your terminal or command prompt

2. Install the GitHub MCP server globally using npm:

   npm install -g @modelcontextprotocol/server-github

3. Verify the installation:

   mcp-server-github --version

Step 2: Create a GitHub Personal Access Token

1. Go to GitHub and sign in to your account
2. Click on your profile picture in the top right corner
3. Select "Settings" from the dropdown menu
4. In the left sidebar, click on "Developer settings"
5. Click on "Personal access tokens" → "Tokens (classic)"
6. Click "Generate new token" → "Generate new token (classic)"
7. Give your token a descriptive name (e.g., "Claude Desktop MCP")
8. Select the following scopes:
   • repo (Full control of private repositories)
   • user:email (Access to user email addresses)
   • read:user (Read access to user profile info)
   • workflow (Update GitHub Action workflows)
9. Click "Generate token"
10. Important: Copy the token immediately and save it securely. You won't be able to see it again.

Step 3: Configure Claude Desktop

For macOS:

1. Open Finder and navigate to ~/Library/Application Support/Claude/
2. Create or edit the claude_desktop_config.json file
3. Add the following configuration:

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_github_token_here"
      }
    }
  }
}

For Windows:

1. Navigate to %APPDATA%\Claude\
2. Create or edit the claude_desktop_config.json file
3. Add the same configuration as above

For Linux:

1. Navigate to ~/.config/Claude/
2. Create or edit the claude_desktop_config.json file
3. Add the same configuration as above

Step 4: Replace the Token

In the configuration file, replace your_github_token_here with the actual token you generated in Step 2.

Example:

{
  "mcpServers": {
    "github": {
      "command": "mcp-server-github",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Step 5: Restart Claude Desktop

1. Completely quit Claude Desktop
2. Restart the application
3. The GitHub MCP server should now be connected

Step 6: Test the Integration

Try asking Claude to perform GitHub-related tasks:

• "List my repositories"
• "Create a new repository called 'test-repo'"
• "Show me the contents of my README file in [repository-name]"
• "Create an issue in [repository-name]"

Available Features

Once configured, Claude can help you with:

• Repository Management: Create, list, and manage repositories
• File Operations: Read, create, and update files in repositories
• Issue Management: Create, list, and update issues
• Pull Request Management: Create, review, and merge pull requests
• Branch Management: Create and manage branches
• Search Operations: Search repositories, code, issues, and users
• Collaboration: Fork repositories, create reviews, and manage collaborators

Troubleshooting

Common Issues:

1. "MCP server not found"

   • Ensure you installed the server globally: npm install -g @modelcontextprotocol/server-github
   • Verify the installation path matches your system's global npm path

2. "Authentication failed"

   • Double-check your GitHub personal access token
   • Ensure the token has the correct scopes
   • Make sure the token hasn't expired

3. "Configuration not loaded"

   • Verify the config file is in the correct location
   • Check that the JSON syntax is valid
   • Ensure Claude Desktop has been restarted after configuration

4. "Permission denied"

   • Check that your GitHub token has the necessary permissions
   • Verify you have access to the repositories you're trying to interact with

Debug Steps:

1. Check the Claude Desktop logs for error messages
2. Verify your configuration file syntax using a JSON validator
3. Test your GitHub token using the GitHub API directly
4. Ensure Node.js and npm are properly installed

Security Considerations

• Store your GitHub personal access token securely
• Use tokens with minimal required permissions
• Regularly rotate your access tokens
• Consider using environment variables instead of hardcoding tokens
• Review and audit repository access regularly

Alternative Configuration with Environment Variables

For enhanced security, you can set the token as an environment variable:

1. Set the environment variable:

   export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

2. Update your configuration:

   {
     "mcpServers": {
       "github": {
         "command": "mcp-server-github",
         "args": [],
         "env": {
           "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
         }
       }
     }
   }

Getting Help

If you encounter issues:

1. Check the official MCP documentation
2. Review the GitHub MCP server repository for updates
3. Verify your GitHub API limits and usage
4. Consult the Claude Desktop support resources

Contributing

If you find issues with this guide or have suggestions for improvement, please create an issue or submit a pull request to this repository.

---

This is generated by Claude for testing purposes.