@cloud9-labs/mcp-github

MCP (Model Context Protocol) server for GitHub API integration. This server provides comprehensive tools for interacting with GitHub repositories, issues, pull requests, branches, and code search through a unified interface.

Features

• Repository Management: List, get, and create repositories
• Issue Tracking: List, get, create, and update GitHub issues
• Pull Requests: List, get, and create pull requests
• Branch Management: List and manage repository branches
• File Content: Retrieve file contents from repositories
• Search: Search repositories and code across GitHub
• Commit History: Access commit information and history

Installation

Prerequisites

• Node.js 18.0 or higher
• A GitHub Personal Access Token

Setup Instructions

1. Create a GitHub Personal Access Token:

   • Go to GitHub Settings - Personal Access Tokens
   • Click "Generate new token" (choose "Tokens (classic)")
   • Grant the following scopes:
     • repo - Full control of private repositories
     • read:user - Read user profile data
   • Copy the generated token (you won't be able to see it again!)

2. Configure Claude Desktop:

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@cloud9-labs/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "your-personal-access-token-here"
      }
    }
  }
}

Config file locations:

• macOS/Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Restart Claude Desktop to load the new MCP server.

Tools

Tool	Description	Parameters
github_list_repos	List repositories for the authenticated user	sort, direction, per_page, page
github_get_repo	Get details of a specific repository	owner, repo
github_create_repo	Create a new repository for the authenticated user	name, description, private, auto_init
github_list_issues	List issues for a repository	owner, repo, state, labels, per_page, page
github_get_issue	Get details of a specific issue	owner, repo, issue_number
github_create_issue	Create a new issue in a repository	owner, repo, title, body
github_update_issue	Update an existing issue	owner, repo, issue_number, title, body, state
github_list_pull_requests	List pull requests for a repository	owner, repo, state, per_page, page
github_get_pull_request	Get details of a specific pull request	owner, repo, pull_number
github_create_pull_request	Create a new pull request	owner, repo, title, body, head, base
github_list_branches	List branches in a repository	owner, repo, per_page, page
github_get_file_content	Get the contents of a file in a repository	owner, repo, path, ref
github_search_repos	Search for repositories on GitHub	query, sort, order, per_page, page
github_search_code	Search for code across GitHub repositories	query, language, per_page, page
github_list_commits	List commits in a repository	owner, repo, sha, per_page, page

Usage Examples

List Your Repositories

User: "Show me my GitHub repositories"
Claude will use: github_list_repos with pagination parameters
Response: A formatted list of your repositories with key information

Search for Repositories

User: "Find popular Python repositories related to AI"
Claude will use: github_search_repos with query and sort parameters
Response: A curated list of matching repositories

Create an Issue

User: "Create a new issue in my-project repository titled 'Bug: Login failure'"
Claude will use: github_create_issue with owner, repo, title, and body
Response: Confirmation with the new issue details including issue number

Get Pull Request Details

User: "Show me the details of pull request #42 in owner/repo"
Claude will use: github_get_pull_request
Response: Complete PR information including status, reviews, and commits

View File Contents

User: "Show me the contents of package.json from owner/repo"
Claude will use: github_get_file_content with path parameter
Response: File contents with optional base64 decoding

Environment Variables

Variable	Required	Description
GITHUB_TOKEN	Yes	GitHub Personal Access Token for API authentication

Authentication

The server uses GitHub's REST API v3 with personal access token authentication. Make sure your token has the appropriate scopes:

• repo - For repository access and management
• read:user - For reading user profile information

Security Note: Never commit your GITHUB_TOKEN to version control. Use environment variables or configuration files that are in .gitignore.

Development

Build from Source

git clone https://github.com/cloud9-labs/mcp-github.git
cd mcp-github
# Install dependencies and build
npm run build

Watch Mode (for development)

npm run dev

This will continuously compile TypeScript as you make changes.

Error Handling

The server provides detailed error messages for:

• Authentication failures (invalid or expired token)
• Rate limiting (GitHub API rate limits)
• Resource not found (non-existent repositories, issues, etc.)
• Validation errors (invalid parameters)
• Network errors (connectivity issues)

All errors are returned in a structured format with the isError flag set to true.

GitHub API Rate Limits

• Authenticated requests: 5,000 requests per hour
• Search API: 30 requests per minute
• GraphQL API: 5,000 points per hour

Monitor your rate limit usage to avoid hitting these limits during intensive operations.

Troubleshooting

"Error: Invalid GITHUB_TOKEN"

• Verify your token is correctly set in the environment
• Ensure the token hasn't expired in GitHub settings
• Check that the token has the required scopes (repo, read:user)

"Error: Repository not found"

• Verify the repository name and owner are correct
• Ensure your token has access to private repositories (if applicable)
• Check repository visibility settings

"Error: Rate limit exceeded"

• Wait for the rate limit to reset (usually 1 hour)
• Reduce the frequency of requests
• Use pagination with per_page and page parameters efficiently

MCP Server Not Loading

• Verify the MCP server is correctly configured in claude_desktop_config.json
• Check that your GITHUB_TOKEN environment variable is set
• Restart Claude Desktop after making configuration changes
• Check the Claude logs for detailed error messages

API Reference

For detailed GitHub API documentation, visit:

• GitHub REST API Documentation
• GitHub Personal Access Token Guide

Support

For issues, questions, or contributions:

• GitHub Issues: cloud9-labs/mcp-github/issues
• GitHub Discussions: cloud9-labs/mcp-github/discussions

License

MIT

Changelog

Version 0.1.0

Initial release with 15 core tools:

• Repository management (list, get, create)
• Issue management (list, get, create, update)
• Pull request management (list, get, create)
• Branch operations (list)
• File content retrieval
• Repository and code search
• Commit history access