Universal GitHub MCP Server

A configurable Model Context Protocol (MCP) server that provides GitHub API integration for any repositories you specify.

🚀 Features

• Pure GitHub API Operations - No local file dependencies
• Multi-Repository Support - Work with multiple GitHub repositories
• Configurable - Easily configure for your own repositories
• Branch Management - Create, list, and manage branches
• Pull Request Operations - Create and manage PRs
• File Operations - Read and update files via GitHub API
• 🆕 Company Documentation Integration - Enforces company rules and best practices
• 🆕 Automatic Validation - Validates branch names, PR formats according to your guidelines
• 🆕 Smart Documentation Search - Find specific rules and guidelines quickly

📋 Available Actions

GitHub Actions

Action	Description
list_repos	Show all configured repositories
list_branches	List branches in a repository
create_branch	Create a new branch (with validation)
list_prs	List open pull requests
create_pr	Create a pull request (with template)
get_file	Get file content from repository
update_file	Update file content in repository

Documentation Actions

Action	Description
list	Show all available company documentation
get	Get specific documentation (git, coding, review, pr)
search	Search through documentation for specific terms
rules	Get company rules for specific categories
guidelines	Get action-specific guidelines

⚙️ Configuration

Method 1: Environment Variable (Recommended)

Set the GITHUB_REPOS environment variable with your repository configuration:

export GITHUB_REPOS='[
  {
    "name": "my-frontend",
    "repo": "myusername/frontend-app",
    "defaultBranch": "main"
  },
  {
    "name": "my-backend",
    "repo": "myusername/backend-api", 
    "defaultBranch": "develop"
  }
]'

Method 2: Configuration File

Edit config/repos.json:

{
  "repositories": [
    {
      "name": "my-project",
      "repo": "owner/repository-name",
      "defaultBranch": "main"
    },
    {
      "name": "another-project",
      "repo": "owner/another-repo",
      "defaultBranch": "develop"
    }
  ]
}

🔑 GitHub Token Setup

1. Generate a Personal Access Token:

   • Go to GitHub → Settings → Developer settings → Personal access tokens
   • Generate new token with repo permissions

2. Set the token as environment variable:

export GITHUB_TOKEN="your_github_token_here"

🏃‍♂️ Running the Server

# Install dependencies
npm install

# Set your GitHub token
export GITHUB_TOKEN="your_token_here"

# Optional: Set custom repositories
export GITHUB_REPOS='[{"name":"my-repo","repo":"owner/repo","defaultBranch":"main"}]'

# Start the MCP server
npm start
# or
node index.js

🔧 Claude Desktop Integration

Add to your Claude Desktop config.json:

{
  "mcpServers": {
    "github-mcp": {
      "command": "node",
      "args": ["/path/to/your/github-mcp/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here",
        "GITHUB_REPOS": "[{\"name\":\"my-repo\",\"repo\":\"owner/repo\",\"defaultBranch\":\"main\"}]"
      }
    }
  }
}

📝 Usage Examples

List Configured Repositories

{
  "repoName": "any-repo-name",
  "action": "list_repos"
}

Create a New Branch

{
  "repoName": "my-frontend",
  "action": "create_branch",
  "taskBranch": "feature/new-component",
  "taskDescription": "Add new React component"
}

Get File Content

{
  "repoName": "my-backend",
  "action": "get_file", 
  "taskDescription": "src/server.js"
}

List Pull Requests

{
  "repoName": "my-frontend",
  "action": "list_prs"
}

🔒 Security Notes

• Never commit your GitHub token to version control
• Use environment variables for sensitive configuration
• The server only requires repo permissions for private repositories
• For public repositories, you can use a token with minimal permissions

🛠 Development

# Clone the repository
git clone <your-repo-url>
cd github-mcp

# Install dependencies  
npm install

# Create your configuration
cp config/repos.json.example config/repos.json
# Edit config/repos.json with your repositories

# Set environment variables
export GITHUB_TOKEN="your_token"

# Run the server
npm start

📄 Example Configuration Files

For Open Source Projects

{
  "repositories": [
    {
      "name": "react",
      "repo": "facebook/react",
      "defaultBranch": "main"
    },
    {
      "name": "vue",
      "repo": "vuejs/vue",
      "defaultBranch": "dev"
    }
  ]
}

For Company Projects

{
  "repositories": [
    {
      "name": "web-app",
      "repo": "company/web-application", 
      "defaultBranch": "develop"
    },
    {
      "name": "mobile-app",
      "repo": "company/mobile-app",
      "defaultBranch": "main"
    },
    {
      "name": "api-service",
      "repo": "company/api-service",
      "defaultBranch": "master"
    }
  ]
}

🎯 Default Behavior

If no configuration is found, the server will use example configuration and show helpful error messages to guide you through setup.

📞 Support

• Check the server logs for configuration loading messages
• Use the list_repos action to verify your configuration
• Ensure your GitHub token has the necessary permissions

---

Ready to use with your own repositories! 🚀