KenkoGeek/mcp-gh-code-review

MCP GitHub Review Server

A production-focused Model Context Protocol (MCP) server for automating GitHub pull request reviews, inline comment threads, and intelligent responses.

Features

• 8 JSON-RPC Tools - 5 PR tools + 3 issue tools + health check
• Webhook Integration - FastAPI endpoint with GitHub signature verification
• Automated Test Suite - Pytest coverage across tools, error handling, and webhook flows
• Structured Logging - JSON logs with rate limit tracking and error context
• Bot Detection - Automatic identification of bot accounts with reply guidance

Quick Start

Installation

Using uvx (recommended - no installation required):

uvx --from git+https://github.com/KenkoGeek/mcp-gh-code-review mcp-gh-review

Or install locally (Python 3.11+):

git clone https://github.com/KenkoGeek/mcp-gh-code-review.git
cd mcp-gh-code-review
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Configuration

cp .env.example .env
# Edit .env with your credentials
# GITHUB_TOKEN=ghp_your_token_here
# GITHUB_REPOSITORY=owner/repo

Required:

• GITHUB_TOKEN - GitHub personal access token with minimal permissions (see below)
• GITHUB_REPOSITORY - Repository in format owner/repo (optional when running inside a git repository with a GitHub remote; the server reads .git/config automatically. If both are present, git detection takes precedence)

GitHub Token Permissions:

Fine-grained Personal Access Token (Recommended):

• Repository permissions:
  • pull_requests: write - Create/update PR comments and reviews
  • issues: write - Add comments to PR discussions
  • metadata: read - Read basic repository information
  • contents: read - Access repository files and structure

Personal Access Token (Classic):

• repo scope - Full repository access

Optional:

• WEBHOOK_SECRET - Secret for webhook signature verification
• LOG_LEVEL - Logging level (DEBUG, INFO, WARNING, ERROR)

Usage

1. MCP Client Integration

Connect from Claude Desktop, IDEs, or any MCP-compatible client.

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

Option A: Using uvx (recommended):

{
  "mcpServers": {
    "github-review": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/KenkoGeek/mcp-gh-code-review",
        "mcp-gh-review"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_REPOSITORY": "owner/repo"
      }
    }
  }
}

Option B: Using local installation:

{
  "mcpServers": {
    "github-review": {
      "command": "/path/to/.venv/bin/python",
      "args": ["-m", "mcp_server.cli", "--stdio"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_REPOSITORY": "owner/repo"
      }
    }
  }
}

Run standalone:

export GITHUB_TOKEN=ghp_your_token_here
export GITHUB_REPOSITORY=owner/repo
python -m mcp_server.cli --stdio

2. Webhook Server

Receive and process GitHub webhook events.

Local development:

uvicorn mcp_server.webhooks:app --reload

Production:

uvicorn mcp_server.webhooks:app --host 0.0.0.0 --port 8000 --workers 4

GitHub Webhook Configuration:

• Payload URL: https://your-domain.com/webhook
• Content type: application/json
• Secret: Set WEBHOOK_SECRET in .env
• Events: Pull requests, Pull request reviews, Issue comments

3. Docker Deployment

Using pre-built image from GitHub Container Registry:

# MCP server
docker run -i \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GITHUB_REPOSITORY=owner/repo \
  ghcr.io/kenkogeek/mcp-gh-code-review:latest

# Webhook server
docker run -p 8000:8000 \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GITHUB_REPOSITORY=owner/repo \
  -e WEBHOOK_SECRET=your_secret \
  ghcr.io/kenkogeek/mcp-gh-code-review:latest \
  uvicorn mcp_server.webhooks:app --host 0.0.0.0

Build locally:

docker build -t mcp-gh-review .

# Run MCP server
docker run -i \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GITHUB_REPOSITORY=owner/repo \
  mcp-gh-review

# Run webhook server
docker run -p 8000:8000 \
  -e GITHUB_TOKEN=ghp_xxx \
  -e GITHUB_REPOSITORY=owner/repo \
  -e WEBHOOK_SECRET=your_secret \
  mcp-gh-review \
  uvicorn mcp_server.webhooks:app --host 0.0.0.0

Development

# Python 3.11+ virtualenv recommended
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

# Lint and test
ruff check src tests
pytest --cov=mcp_server --cov-report=term --cov-report=xml

Available Tools

Pull Request Tools

Issue Tools

System Tools

Example Prompts

For pull request reviews:

• "Review PR #15 and suggest improvements"
• "Analyze the changes in PR #23 and check for security issues"
• "What are the unresolved comments in PR #8?"
• "Reply to all unresolved comments in PR #12"
• "Submit my pending review as APPROVE"

For issue management:

• "List all open issues in the repository"
• "Review issue #10 and provide feedback"
• "Reply to issue #5 with a status update"
• "Show me all closed issues"

The MCP server automatically:

• Detects bot comments (won't reply to dependabot)
• Identifies your own comments (won't reply to yourself)
• Provides context-aware guidance for responses

Development

Testing

pip install -e .[dev]
pytest
pytest --cov=mcp_server  # With coverage

Linting

ruff check src/
mypy src/

Architecture

See for detailed component diagrams and data flow.

GitHub Webhooks → FastAPI → MCP Server → GitHub REST/GraphQL APIs

Monitoring

Webhook Health Endpoint:

curl http://localhost:8000/health

Response:

{
  "status": "ok"
}

MCP Health Tool (health):

• Returns GitHub REST and GraphQL rate-limit telemetry for connected token
• Surfaces cached counts from GitHubClient and GitHubGraphQLClient
• Useful for deciding when to throttle automation

Structured Logs:

• All operations logged with structlog
• JSON format for easy parsing
• Includes context: event IDs, actors, actions

Security

• Webhook Verification - X-Hub-Signature-256 HMAC validation
• Token Security - Never logged, use environment variables or secret managers
• Non-root Container - Docker runs as unprivileged app user
• Input Validation - Pydantic models validate all inputs
• Rate Limit Tracking - Monitors GitHub API limits

Troubleshooting

Rate Limit Issues

Check current limits:

curl http://localhost:8000/health | jq .rate_limit

Solutions:

• Use GitHub App for higher limits (5000/hour vs 60/hour)
• Enable conditional requests with ETags
• Implement request caching

Authentication Errors

401 Unauthorized:

# Verify token has required permissions
gh auth status
# Regenerate token if expired

403 Forbidden:

• Check repository access permissions
• Verify token scopes include repo or fine-grained permissions
• Ensure not hitting secondary rate limits

Webhook Issues

Signature verification fails:

# Verify WEBHOOK_SECRET matches GitHub configuration
echo $WEBHOOK_SECRET
# Check webhook delivery logs in GitHub settings

Payload validation errors:

• Ensure webhook sends application/json content type
• Verify payload includes required action field
• Check GitHub webhook delivery response for details

Connection Errors

Network timeouts:

# Test GitHub API connectivity
curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

Solutions:

• Check firewall/proxy settings
• Verify DNS resolution for api.github.com
• Enable retry logic (already implemented for network errors)

Logging and Debugging

Enable debug logging:

export LOG_LEVEL=DEBUG
python -m mcp_server.cli --stdio

View structured logs:

# Logs output to stderr in JSON format
python -m mcp_server.cli --stdio 2> debug.log
jq . debug.log  # Pretty print JSON logs

Common log events:

• github_api_request - API calls with method, path, status
• review_pr_start / review_pr_complete - Tool invocations
• error - Failures with context and GitHub error messages

Contributing

License

MIT License - See for details.