GitHub Analytics MCP Server

GitHub Analytics MCP Server — Architecture Reference Project

Query, analyze, and visualize any public GitHub repository — from the command line, browser, or AI agent.

Overview

GitHub Analytics MCP Server is a production-ready microservice that turns the GitHub API into a simple, self-hosted analytics endpoint. Point it at any public repository and instantly get structured data on stars, forks, contributors, commit history, and language distribution.

It exposes two interfaces: a RESTful API (FastAPI with auto-generated Swagger docs) for direct HTTP access, and a Model Context Protocol (MCP) server that lets AI agents like Claude Desktop query GitHub data as a native tool.

The entire stack — API gateway, MCP server, container orchestration, infrastructure provisioning, and CI/CD — is included and deployable with a single command.

This project also serves as an architecture reference implementation: every layer is accompanied by design-decision documentation explaining why it is structured this way, not just what it does.

Features

• 🔍 Query any public GitHub repository by owner/name
• 📊 Repository statistics — stars, forks, issues, watchers
• 👥 Contributor analysis — top contributors with commit counts
• 📝 Commit history — recent commits with author and message details
• 🌐 RESTful API with auto-generated OpenAPI/Swagger docs
• 🤖 MCP Protocol support for AI agent integration (Claude Desktop, etc.)
• 🐳 Production-ready with Docker multi-stage builds and Docker Compose
• ☸️ Kubernetes deployment with Deployments, Services, Ingress, and HPA
• 📈 Auto-scaling — Horizontal Pod Autoscaler (2–5 replicas, 70% CPU target)
• 🔄 Full CI/CD pipeline — lint, test, build, and deploy via GitHub Actions
• 🏗️ Infrastructure as Code — Terraform provisions the entire K8s stack

Why This Project?

This is not just a tool — it is a reference implementation designed for studying architecture patterns. Every layer includes design-decision documentation explaining the reasoning behind its structure.

Architecture

graph TB
    subgraph "User Interface"
        A[Web Browser / CLI]
    end

    subgraph "API Layer"
        B[FastAPI GatewayPort 8080]
        C[MCP Serverstdio mode]
    end

    subgraph "Container Orchestration"
        D[Kubernetes Cluster]
        E[Docker Containers]
        F[Auto-scaling HPA]
    end

    subgraph "External Services"
        G[GitHub API]
    end

    subgraph "Infrastructure"
        H[Terraform IaC]
        I[CI/CD Pipeline]
    end

    A -->|HTTP/REST| B
    A -->|MCP Protocol| C
    B -->|GitHub Token| G
    C -->|GitHub Token| G
    B -.->|Deployed in| D
    C -.->|Deployed in| D
    D -->|Manages| E
    D -->|Auto-scales| F
    H -.->|Provisions| D
    I -.->|Deploys to| D

Design Philosophy

One domain, two interfaces, shared core

GitHubClient is the single business-logic layer. The MCP Server and FastAPI Gateway are both thin adapters — they translate between their respective protocols and the shared core. Neither contains business logic, and neither duplicates the other.

Why two interfaces: MCP serves AI agents over stdio; REST serves humans and programs over HTTP. Two protocols, two adapters, zero duplicated logic.

Error handling strategy

Custom exception hierarchy (RepositoryNotFoundError, AuthenticationError, RateLimitError) translates GitHub HTTP status codes into semantic domain errors. The MCP server converts these into user-friendly text messages; the FastAPI gateway converts them into the corresponding HTTP status codes (404/401/429/502). Callers never need to know how the GitHub API works internally.

Infrastructure: three layers for three use cases

• Docker Compose — local development. One command (docker-compose up) starts everythi