sitetracker-github-mcp 2.4.0
MCP server for GitHub with 64 tools - natural language queries, PRs, issues, file operations, branches, forks, releases, workflows, teams, and more
License: MIT
Requires Python: >=3.10
Keywords: github, mcp, claude, ai, llm, devtools

<p align="center">
  <img src="assets/logo.png" alt="GitHub MCP Server" width="200">
</p>

# GitHub MCP Server with Compass Smart Query

A Model Context Protocol (MCP) server for GitHub that enables natural language queries and comprehensive GitHub operations through Claude Desktop.

## Features

- **🧭 Compass Smart Query**: Natural language to GitHub search syntax translation
- **🔐 Flexible Auth**: PAT (Personal Access Token) or OAuth 2.0
- **📦 46 Tools**: Issues, PRs, repos, workflows, security, CI/CD, analytics, teams
- **🔒 Security Scanning**: Dependabot, code scanning, secret scanning alerts
- **📊 Analytics**: Repo stats, traffic, contributors, community health
- **⚡ Retry Logic**: Automatic retry with exponential backoff for rate limiting
- **🔍 Context Discovery**: Auto-discover orgs, repos, and labels for smart queries

## Quick Start (Sitetracker Engineers)

### One-Line Install

```bash
curl -fsSL https://raw.githubusercontent.com/sitetracker/github-mcp-server/main/setup.sh | bash
```

Then:
1. Get the OAuth secret from your team lead or #engineering Slack
2. Edit `~/github-mcp-server/.env` and add the secret
3. Restart Claude Desktop
4. Type "authorize github" → browser login → done!

---

### Manual Install

#### 1. Clone & Install

```bash
git clone https://github.com/sitetracker/github-mcp-server.git
cd github-mcp-server
chmod +x install.sh
./install.sh
```

#### 2. Configure

```bash
cp .env.example .env
```

Edit `.env` and add the OAuth secret (get from team lead):
```
GITHUB_OAUTH_CLIENT_SECRET=<your secret here>
```

#### 3. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "github-mcp": {
      "command": "/Users/YOUR_USERNAME/github-mcp-server/venv/bin/python",
      "args": ["/Users/YOUR_USERNAME/github-mcp-server/src/github_mcp/server.py"]
    }
  }
}
```

**Replace `YOUR_USERNAME`** with your Mac username (run `whoami` to check).

#### 4. Authorize

1. **Restart Claude Desktop**
2. Start a new chat and type: "authorize github"
3. Browser opens → log in with your GitHub account
4. Done! Try: "show open PRs in strk"

---

## Alternative: Personal Access Token

If you prefer PAT over OAuth:

1. Create a token at: https://github.com/settings/tokens
2. Select scopes: `repo`, `read:org`, `read:user`, `workflow`
3. Add to `.env`:
   ```
   GITHUB_TOKEN=ghp_your_token_here
   GITHUB_DEFAULT_ORG=Sitetracker
   ```

## Tools (46 Total)

### Smart Query (Primary)

| Tool | Description |
|------|-------------|
| `github_smart_query` | **PRIMARY** - Natural language to GitHub search |
| `github_compass_setup` | Auto-discover orgs, repos, labels for context |
| `github_search` | Raw GitHub search syntax |

### Authentication

| Tool | Description |
|------|-------------|
| `github_authorize` | Verify/initiate authentication |
| `github_logout` | Remove stored OAuth tokens |
| `github_get_user` | Get user information |

### Repositories

| Tool | Description |
|------|-------------|
| `github_list_repos` | List org/user repositories |
| `github_get_repo` | Get repository details |

### Issues

| Tool | Description |
|------|-------------|
| `github_list_issues` | List repository issues |
| `github_get_issue` | Get issue details with comments |
| `github_create_issue` | Create new issue |
| `github_update_issue` | Update issue (title, state, labels, assignees) |
| `github_add_issue_comment` | Add comment to issue |

### Pull Requests

| Tool | Description |
|------|-------------|
| `github_list_prs` | List pull requests |
| `github_get_pr` | Get PR details with reviews |
| `github_create_pr` | Create new PR |
| `github_merge_pr` | Merge a PR (merge, squash, or rebase) |
| `github_review_pr` | Submit PR review (approve, request changes, comment) |

### PR Review Details

| Tool | Description |
|------|-------------|
| `github_list_pr_comments` | List inline code review comments |
| `github_add_pr_comment` | Add inline comment on specific line |
| `github_list_pr_files` | List files changed in PR with +/- counts |
| `github_request_reviewers` | Request reviewers (users or teams) |

### Branches & Commits

| Tool | Description |
|------|-------------|
| `github_list_branches` | List repository branches |
| `github_list_commits` | List commits with filtering |

### Code & File Operations

| Tool | Description |
|------|-------------|
| `github_get_file_contents` | Read file contents from repo |
| `github_get_directory` | List files in a directory |
| `github_compare_branches` | Diff between branches/tags/commits |
| `github_get_blame` | Get commit history for a file |

### Workflows (GitHub Actions)

| Tool | Description |
|------|-------------|
| `github_list_workflows` | List repository workflows |
| `github_list_workflow_runs` | List workflow runs with status |
| `github_trigger_workflow` | Trigger workflow dispatch |
| `github_rerun_workflow` | Re-run workflow (all or failed jobs) |
| `github_cancel_workflow` | Cancel running workflow |

### CI/CD Status

| Tool | Description |
|------|-------------|
| `github_get_commit_status` | Combined status for a ref (branch/tag/SHA) |
| `github_list_check_runs` | List check runs (tests, lint, etc.) |
| `github_get_check_run` | Detailed check with annotations |

### Security & Compliance ⚠️

> **Note:** These tools require a **Classic PAT** with `security_events` scope. They do not work with OAuth due to GitHub API restrictions. See [Security Tools Setup](#security-tools-setup) below.

| Tool | Description |
|------|-------------|
| `github_list_dependabot_alerts` | Vulnerability alerts for dependencies |
| `github_list_code_scanning_alerts` | CodeQL/security scan results |
| `github_list_secret_scanning_alerts` | Exposed secrets/credentials |
| `github_get_security_advisories` | Repository security advisories |

### Releases

| Tool | Description |
|------|-------------|
| `github_list_releases` | List repository releases |
| `github_create_release` | Create new release |

### Repository Analytics

| Tool | Description |
|------|-------------|
| `github_get_repo_stats` | Contributors, commit activity, code frequency |
| `github_get_traffic` | Views, clones, referrers (requires push access) |
| `github_get_contributors` | Top contributors with commit counts |
| `github_get_community_profile` | Health score (README, LICENSE, etc.) |

### Organization / Teams

| Tool | Description |
|------|-------------|
| `github_list_teams` | List teams in org |
| `github_get_team` | Team details with members |
| `github_list_team_repos` | Repos a team has access to |

## Smart Query Examples

```
"open PRs"                    → is:pr is:open
"my issues"                   → is:issue assignee:@me
"bugs this week"              → is:issue label:bug created:>=<week-ago>
"merged PRs"                  → is:pr is:merged
"stale issues"                → is:issue is:open updated:<30-days-ago>
"needs review"                → is:pr is:open review:none
"PRs by username"             → is:pr author:username
"high priority bugs"          → is:issue label:priority:high
"draft PRs"                   → is:pr draft:true
"approved PRs ready to merge" → is:pr review:approved is:open
```

## Compass Context

Run `github_compass_setup` to auto-discover:
- Organizations you belong to
- Repositories in your default org
- Labels from your repositories

This enables smart query aliases. Context is stored in `~/.github-mcp-compass/`.

### Context Files

| File | Purpose |
|------|---------|
| `instance_context.json` | Default org, repo, user |
| `org_map.json` | Organization aliases |
| `repo_map.json` | Repository aliases |
| `label_map.json` | Label aliases |

## Security Tools Setup

The 4 security scanning tools require a **Classic Personal Access Token** due to GitHub API restrictions on OAuth apps accessing security data.

### For DevOps/Security Team Members

1. Create a Classic PAT at: https://github.com/settings/tokens
2. Select scopes: `repo`, `security_events`
3. Add to your `~/.github-mcp-server/.env`:
   ```
   GITHUB_TOKEN=ghp_your_classic_token
   ```
4. Restart Claude Desktop

When `GITHUB_TOKEN` is set, it takes precedence over OAuth and enables security tools.

### For Everyone Else

The other 42 tools work fine with OAuth - no action needed.

## Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `GITHUB_TOKEN` | Personal Access Token | Yes (or OAuth) |
| `GITHUB_OAUTH_CLIENT_ID` | OAuth Client ID | No (alt auth) |
| `GITHUB_OAUTH_CLIENT_SECRET` | OAuth Client Secret | No (alt auth) |
| `GITHUB_DEFAULT_ORG` | Default organization | No |
| `GITHUB_DEFAULT_REPO` | Default repository | No |
| `GITHUB_MCP_LOG_LEVEL` | Logging level (DEBUG, INFO, etc.) | No |

## Rate Limiting

The server automatically handles GitHub's rate limiting:
- Respects `Retry-After` and `X-RateLimit-Reset` headers
- Exponential backoff for retries
- Maximum 3 retries by default

## Example Use Cases

### Security Review
```
"Show me all critical Dependabot alerts for sitetracker/main-repo"
"List open secret scanning alerts"
"What code scanning issues are on the main branch?"
```

### CI/CD Monitoring
```
"What's the CI status for PR #123?"
"List failed workflow runs this week"
"Re-run the failed tests for run 12345"
```

### Release Management
```
"Compare main to v2.5.0 - what's in this release?"
"Show me all commits since the last release"
"List files changed in PR #456"
```

### Team Analytics
```
"Who are the top contributors to the platform repo?"
"What's our repo traffic this week?"
"List all teams and their access levels"
```

## Development

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run server directly
python src/github_mcp/server.py
```

## License

MIT

## Credits

Inspired by the [Jira MCP Compass](https://github.com/sitetracker/jira-mcp-compass) server architecture.