GitHub MCP Server

A Model Context Protocol (MCP) server that provides comprehensive GitHub repository operations through a simple CLI interface.

Features

• 🔍 Repository exploration and file content retrieval
• 📄 README and file content access
• 🔎 Code search within repositories
• 📋 Issues and pull requests management
• 🌿 Branch and commit information
• 👤 User information lookup
• 🚀 Rate limiting and error handling
• 📦 Easy npx installation

Installation & Usage

Quick Start (Recommended)

# Run directly with npx (no installation needed)
npx @ildunari/github-mcp-server --github-token YOUR_GITHUB_TOKEN

# Or use environment variable
export GITHUB_TOKEN=your_token_here
npx @ildunari/github-mcp-server --github-token $GITHUB_TOKEN

Global Installation

npm install -g @ildunari/github-mcp-server
@ildunari/github-mcp-server --github-token YOUR_GITHUB_TOKEN

GitHub Token Setup

1. Go to GitHub Settings → Developer settings → Personal access tokens

2. Generate a new token (classic) with these scopes:

   • repo (for private repositories)
   • public_repo (for public repositories)
   • read:user (for user information)

3. Use the token with the CLI:

npx @ildunari/github-mcp-server --github-token ghp_your_token_here

Available Tools

Repository Operations

• github_repo_info - Get repository information
• github_list_contents - List directory contents
• github_get_file_content - Get file content
• github_get_readme - Get repository README
• github_search_code - Search code in repository

Issues & Pull Requests

• github_list_issues - List repository issues
• github_get_issue - Get specific issue details
• github_list_pulls - List pull requests
• github_get_pull - Get specific pull request details

Repository Management

• github_list_branches - List repository branches
• github_user_info - Get user information

CLI Options

Options:
  -t, --github-token  GitHub access token for API requests [required]
  -r, --rate-limit    Rate limit delay in ms between requests [default: 100]
  -h, --help          Show help

Examples

Basic Usage

# Start the MCP server
npx @ildunari/github-mcp-server --github-token YOUR_TOKEN

# The server will run on stdio and accept MCP requests

With Custom Rate Limiting

# Slower rate limiting (500ms between requests)
npx @ildunari/github-mcp-server --github-token YOUR_TOKEN --rate-limit 500

MCP Client Configuration

For use with Claude Desktop or other MCP clients:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@ildunari/github-mcp-server", "--github-token", "YOUR_GITHUB_TOKEN"]
    }
  }
}

Response Formats

All tools support two detail levels:

• summary (default) - Condensed information
• detailed - Full API response

Example tool call:

{
  "name": "github_repo_info",
  "arguments": {
    "repo_url": "https://github.com/microsoft/vscode",
    "detail_level": "summary"
  }
}

Error Handling

The server includes comprehensive error handling for:

• Invalid GitHub URLs
• API rate limits
• Authentication errors
• Network issues
• File encoding problems

License

MIT License

Author

ildunari

Contributing

1. Fork the repository
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request