auricle-inc/github-cli-mcp

GitHub CLI MCP Server

A production-ready Model Context Protocol (MCP) server that wraps the GitHub CLI (gh) to provide enhanced GitHub operations for AI agents and Claude Code.

Overview

This MCP server bridges the gap between AI agents and GitHub operations by providing a clean, typed interface to GitHub CLI functionality. It offers better performance, caching, and error handling compared to direct API calls while maintaining compatibility with existing GitHub CLI configurations.

Features

Core GitHub Operations

• Repository Management: Create, clone, view, fork, and manage repositories
• Issue Tracking: List, create, view, close, and manage issues
• Pull Requests: Create, review, merge, and manage pull requests
• Workflows: Run, monitor, and manage GitHub Actions workflows
• Releases: Create, view, and manage releases
• Direct API Access: Raw GitHub API calls with authentication

Enhanced Capabilities

• Smart Caching: Configurable response caching for better performance
• Authentication Management: Support for PAT, OAuth, and SSH authentication
• Error Recovery: Intelligent retry logic and error handling
• Pydantic V2 Models: Fully typed data structures for reliability
• Claude CLI Compatible: Optimized schemas for Claude Code integration

Performance Features

• Connection Pooling: Efficient HTTP connection management
• Rate Limiting: Built-in GitHub API rate limit handling
• Concurrent Operations: Async support for multiple operations
• Response Streaming: Handle large responses efficiently

Quick Start

Prerequisites

1. GitHub CLI: Install the GitHub CLI

   # Ubuntu/Debian
   sudo apt install gh
   
   # Or download from https://cli.github.com/
   

2. Authentication: Set up GitHub CLI authentication

   gh auth login
   

3. Python Environment: Python 3.11+ with UV

   # Install UV if not available
   curl -LsSf https://astral.sh/uv/install.sh | sh
   

Installation

Development Installation

# Clone and setup
git clone <repository-url>
cd github-cli-mcp

# Setup development environment
make dev

# Or using just
just dev

Production Installation

# Install from PyPI (when published)
uv pip install github-cli-mcp

# Or install directly
make install

Configuration

1. Environment Setup:

   cp .env.example .env
   # Edit .env with your configuration
   

2. MCP Registration: Add to your Claude configuration

   make mcp-install
   

Usage

As MCP Server

# Start stdio server (for Claude CLI)
uv run python -m github_mcp.server --stdio

# Test server
make mcp-test

Command Examples

The server provides these main tool categories:

Repository Operations

# Get repository information
await repo_info(owner="octocat", repo="Hello-World")

# List repositories
await list_repos(owner="octocat", type="public")

# Create repository
await create_repo(name="new-repo", description="A new repository")

Issue Management

# List issues
await list_issues(owner="owner", repo="repo", state="open")

# Create issue
await create_issue(
    owner="owner",
    repo="repo",
    title="Bug report",
    body="Issue description"
)

Pull Request Operations

# List pull requests
await list_prs(owner="owner", repo="repo", state="open")

# Create pull request
await create_pr(
    owner="owner",
    repo="repo",
    title="Feature addition",
    body="PR description",
    head="feature-branch",
    base="main"
)

Workflow Management

# List workflows
await list_workflows(owner="owner", repo="repo")

# Run workflow
await run_workflow(
    owner="owner",
    repo="repo",
    workflow_id="ci.yml",
    ref="main"
)

Architecture

High-Level Design

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Claude CLI    │────│  MCP Protocol   │────│  GitHub CLI     │
│                 │    │                 │    │                 │
│  AI Agents      │    │  This Server    │    │  gh commands    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │
                       ┌─────────────────┐
                       │   GitHub API    │
                       │                 │
                       │  Rate Limiting  │
                       │   Caching       │
                       └─────────────────┘

Component Overview

• MCP Server: Handles protocol communication with Claude
• GitHub CLI Wrapper: Manages gh command execution
• Authentication Layer: Handles multiple auth methods
• Caching System: Configurable response caching
• Error Handling: Comprehensive error recovery
• Type System: Pydantic V2 models for data validation

Development

Development Setup

# Quick setup
make dev

# Manual setup
uv sync --frozen --all-extras
uv run pre-commit install

Testing

# Run all tests
make test

# Test with coverage
make test-cov

# Test MCP compliance
make mcp-test

# Quick development cycle
just quick

Code Quality

# Format code
make format

# Lint code
make lint

# Type checking
make type-check

# All checks
make all

Project Structure

src/github_mcp/
├── __init__.py          # Package initialization
├── server.py            # Main MCP server implementation
├── models.py            # Pydantic V2 data models
├── tools.py             # MCP tool implementations
├── github_cli.py        # GitHub CLI wrapper
├── auth.py              # Authentication management
├── cache.py             # Caching layer
├── config.py            # Configuration management
├── exceptions.py        # Custom exceptions
└── utils.py             # Utility functions

tests/
├── test_server.py       # Server tests
├── test_github_cli.py   # CLI wrapper tests
├── test_tools.py        # Tool implementation tests
└── integration/         # Integration tests with real gh CLI

Configuration

Environment Variables

See .env.example for all available configuration options.

Key settings:

• GITHUB_TOKEN: GitHub Personal Access Token
• CACHE_ENABLED: Enable response caching
• MCP_LOG_LEVEL: Logging level
• RATE_LIMIT_ENABLED: Enable rate limiting

MCP Configuration

The server integrates with Claude CLI via MCP configuration:

{
  "mcpServers": {
    "github-cli-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "github_mcp.server", "--stdio"],
      "cwd": "/home/david/projects/mcp/github"
    }
  }
}

Authentication

Supported Methods

1. Personal Access Token (PAT): Recommended for servers
2. OAuth Flow: For interactive applications
3. SSH Keys: For Git operations
4. GitHub CLI Auth: Uses existing gh auth configuration

Setup

# Using GitHub CLI (recommended)
gh auth login

# Or set environment variable
export GITHUB_TOKEN=ghp_your_token_here

Performance

Caching Strategy

• Memory Cache: Default for development
• Redis Cache: Available for production
• TTL Configuration: Configurable cache expiration
• Cache Invalidation: Smart cache updates

Rate Limiting

• GitHub API Limits: Automatic rate limit handling
• Concurrent Requests: Configurable concurrency limits
• Backoff Strategy: Exponential backoff on rate limits

Deployment

Production Deployment

1. Configure Environment: Set production environment variables
2. Install Dependencies: make install
3. Register MCP Server: make mcp-install
4. Monitor Health: Use built-in health checks

Docker Deployment

FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN make install
CMD ["python", "-m", "github_mcp.server", "--stdio"]

Contributing

See for development guidelines.

Quick Contribution

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run make all to validate
5. Submit a pull request

License

MIT License - see for details.

Support

• Documentation:
• Issues: GitHub Issues
• Development: See

Roadmap

See and for planned features and improvements.