GitHub Analytics MCP Server

A production-grade Model Context Protocol (MCP) 2.x server for GitHub analytics.

This project goes beyond a basic MCP tutorial and demonstrates how to build an MCP server with the engineering patterns you actually need for real-world use:

• Async HTTP

• Connection pooling

• Explicit timeouts

• TTL caching

• GitHub rate-limit awareness

• Retry with exponential backoff

• Structured logging

• Input validation

• Parallel API requests

• Clean MCP lifecycle management

• Real end-to-end MCP protocol testing

Built as part of the Production AI Engineering series on Agentic Data Lab.

🎥 YouTube: Agentic Data Lab

What Does This MCP Server Do?

The server exposes GitHub repository analytics as MCP tools.

An MCP-compatible AI client can use it to:

• inspect repository metadata

• retrieve recent commits

• analyze contributors

• inspect open issues

• analyze commit activity

• compare two repositories

• inspect GitHub API rate limits

Example:

User:
Compare pallets/flask and django/django.

Which repository looks more active?

The AI client can call:

compare_repos

and retrieve live GitHub data through this MCP server.

Architecture

                ┌─────────────────────┐
                │   MCP Client / AI   │
                │ Claude / MCP Client │
                └──────────┬──────────┘
                           │
                           │ MCP stdio
                           ▼
                ┌─────────────────────┐
                │ GitHub Analytics    │
                │     MCP Server      │
                └──────────┬──────────┘
                           │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
          Input Validation       TTL Cache
                                     │
                           ┌─────────┴─────────┐
                           │                   │
                      CACHE HIT          CACHE MISS
                           │                   │
                           │                   ▼
                           │          Async HTTP Client
                           │                   │
                           │          Retry + Backoff
                           │                   │
                           │                   ▼
                           │            GitHub REST API
                           │                   │
                           └───────────◄───────┘
                                       │
                                       ▼
                               Structured MCP Result

7 Production Patterns Implemented

1. Async HTTP + Connection Pooling

The server uses:

httpx.AsyncClient

instead of synchronous HTTP requests.

The HTTP client is created once during the MCP server lifecycle and reused across tool calls.

This provides:

• non-blocking I/O

• connection reuse

• better concurrency

• explicit timeout control

The server configures separate timeouts for:

connect
read
write
pool

Related MCP server: ship-it-mcp

2. TTL Caching

AI clients may call the same MCP tool several times during one conversation.

Instead of hitting GitHub every time, the server caches responses in memory.

Example:

First request

MCP Client
    │
    ▼
MCP Server
    │
    ▼
GitHub API
    │
    ▼
Cache

Second request:

MCP Client
    │
    ▼
MCP Server
    │
    ▼
CACHE HIT

No additional GitHub request is required.

Different tools use different TTLs depending on how quickly their data changes.

3. GitHub Rate-Limit Awareness

GitHub exposes rate-limit information through response headers.

The server tracks:

X-RateLimit-Limit
X-RateLimit-Used
X-RateLimit-Remaining
X-RateLimit-Reset
Retry-After

The server can detect when GitHub is actually rate limiting requests and return a useful MCP tool error instead of exposing a raw exception.

4. Retry + Exponential Backoff

Transient network failures and upstream 5xx responses are retried automatically.

Retry sequence:

Attempt 1
   │
   └── failure
        │
        ▼
      wait 1s

Attempt 2
   │
   └── failure
        │
        ▼
      wait 2s

Attempt 3
   │
   └── final result

The backoff formula is:

2 ** (attempt - 1)

The server does not blindly retry normal 4xx client errors.

5. Structured Logging

MCP stdio uses stdout for protocol communication.

Operational logs are therefore written separately through Python logging.

Example:

2026-08-27T14:14:03 | INFO | Starting GitHub Analytics MCP server
2026-08-27T14:14:04 | INFO | GET /repos/facebook/react → 200
2026-08-27T14:14:04 | INFO | CACHE HIT /repos/facebook/react

This makes it easy to inspect:

• API requests

• HTTP status

• latency

• retry attempts

• cache hits

• validation failures

• rate-limit warnings

6. Input Validation

Repository owner and repository names are validated before any network request is made.

Valid names may contain:

letters
numbers
.
-
_

For example:

face../../book

is rejected locally before it can become part of a GitHub API request.

7. Parallel API Requests

The compare_repos MCP tool needs information from two independent repositories.

Instead of fetching them sequentially:

repo_a = await get_repo_a()
repo_b = await get_repo_b()

the server runs both requests concurrently:

repo_a, repo_b = await asyncio.gather(
    get_repo_a(),
    get_repo_b(),
)

Conceptually:

Sequential

Repo A ───────────────► Done
                        Repo B ───────────────► Done


Parallel

Repo A ───────────────► Done
Repo B ───────────────────► Done

This reduces elapsed wait time when requests are independent.

Available MCP Tools

The server currently exposes 7 MCP tools.

get_repo_overview

Returns:

• stars

• forks

• open issues

• watchers

• language

• topics

• license

• last push date

• homepage

• repository size

Example:

get_repo_overview(
    owner="facebook",
    repo="react"
)

list_recent_commits

Returns recent repository commits.

Example:

list_recent_commits(
    owner="vuejs",
    repo="core",
    limit=5
)

get_contributors

Returns top repository contributors.

Example:

get_contributors(
    owner="django",
    repo="django",
    limit=10
)

list_open_issues

Returns open GitHub issues while excluding pull requests.

Example:

list_open_issues(
    owner="pallets",
    repo="flask",
    limit=10
)

get_commit_activity

Returns repository commit activity including:

• total commits

• average commits per week

• peak activity

• recent weekly activity

compare_repos

Compares two repositories side by side.

Example:

compare_repos(
    owner1="pallets",
    repo1="flask",
    owner2="django",
    repo2="django"
)

Returned fields include:

stars
forks
open issues
language
last push

get_rate_limit_status

Returns GitHub API rate-limit information plus local MCP server counters.

Example:

{
  "limit": 60,
  "used": 4,
  "remaining": 56,
  "resets_in_seconds": 3599,
  "server_outbound_http_requests": 4,
  "server_cache_hits": 1
}

Actual values depend on your current GitHub API usage.

Project Structure

mcp-github-analytics/
│
├── server.py
│   └── Main MCP server and GitHub tools
│
├── demo_mcp.py
│   └── Real end-to-end MCP client demo
│
├── requirements.txt
│   └── Python dependencies
│
├── .env.example
│   └── Environment variable template
│
└── .gitignore

Setup

1. Clone the Repository

git clone https://github.com/sweta2503/mcp-github-analytics.git

Move into the project:

cd mcp-github-analytics

2. Create a Virtual Environment

python -m venv .venv

macOS / Linux

source .venv/bin/activate

Windows

.venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

The project uses:

mcp[cli]==2.1.1
httpx==0.28.1
python-dotenv==1.2.3

GitHub Token Setup

A GitHub token is optional when working only with public repositories, but it is recommended.

Copy the example environment file:

cp .env.example .env

Add your GitHub token:

GITHUB_TOKEN=your_github_token_here

Do not commit your real .env file or token.

Run the Real MCP Demo

Run:

python demo_mcp.py

This is a real MCP end-to-end test.

demo_mcp.py does not simply import the functions from server.py.

Instead it:

1. Starts server.py as an MCP subprocess
2. Connects using MCP stdio
3. Negotiates the MCP protocol
4. Discovers the MCP tools
5. Calls the tools through MCP
6. Receives structured MCP responses

You should see output similar to:

MCP CONNECTED — discover the real server tools

Negotiated protocol: ...
Tools discovered (7):
get_repo_overview
list_recent_commits
get_contributors
list_open_issues
get_commit_activity
compare_repos
get_rate_limit_status

Test the Cache

The demo calls:

get_repo_overview(facebook/react)

twice.

The first call hits GitHub.

The second should show:

CACHE HIT

and return significantly faster.

Test Parallel Repository Comparison

The demo also runs:

compare_repos(
    pallets/flask,
    django/django
)

Both upstream GitHub requests are fired concurrently through:

asyncio.gather(...)

Capture Demo Output and Server Logs

You can capture the MCP client output and server logs separately:

python demo_mcp.py > demo_output.txt 2> server.log

This creates:

demo_output.txt

for MCP client responses and:

server.log

for server-side logs.

The server log contains useful information such as:

GET /repos/facebook/react → 200
CACHE HIT /repos/facebook/react
GET /repos/pallets/flask → 200
GET /repos/django/django → 200

Run the Server Directly

You can start the MCP server itself with:

python server.py

The server runs over MCP stdio.

Normally an MCP-compatible client launches this process automatically.

Connect the Server to Claude Desktop

You do not need to keep a machine-specific claude_desktop_config.json inside this repository.

Instead, add the server to your local Claude Desktop configuration.

Example:

{
  "mcpServers": {
    "github-analytics": {
      "command": "/ABSOLUTE/PATH/TO/mcp-github-analytics/.venv/bin/python",
      "args": [
        "/ABSOLUTE/PATH/TO/mcp-github-analytics/server.py"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN"
      }
    }
  }
}

Replace:

/ABSOLUTE/PATH/TO/mcp-github-analytics

with the actual project location on your computer.

Never commit your real GitHub token.

After restarting Claude Desktop, the GitHub analytics tools should become available to Claude.

Example prompt:

Compare pallets/flask and django/django.

Which repository appears more active?

Use the GitHub MCP tools and explain which data you used.

End-to-End Request Flow

User
 │
 ▼
Claude / MCP Client
 │
 │ MCP tool call
 ▼
GitHub Analytics MCP Server
 │
 ├── Validate input
 │
 ├── Check TTL cache
 │
 ├── Cache hit ──────────────► Return result
 │
 └── Cache miss
          │
          ▼
     Async HTTP
          │
     Retry / Backoff
          │
          ▼
     GitHub REST API
          │
          ▼
       Response
          │
          ▼
       TTL Cache
          │
          ▼
 Structured MCP Response
          │
          ▼
     AI / MCP Client

Local vs Distributed Production MCP

This project intentionally uses an in-memory TTL cache because it is designed as a clear local/stdio MCP example.

For a multi-instance remote MCP deployment, you would typically replace process-local state with infrastructure such as:

Redis
PostgreSQL
distributed rate limiting
centralized observability
authentication
tracing

The patterns demonstrated in this repository are the building blocks for that next stage.

Watch the Full Build

I explain the architecture, code, caching, retry logic, validation, parallel requests and real MCP demo on my YouTube channel:

🎥 Agentic Data Lab

https://www.youtube.com/@agenticdatalab

On the channel I cover:

• Production AI Engineering

• MCP

• AI Agents

• LangGraph

• RAG

• AI evaluations

• Agent observability

• AI system design

• Data Engineering + AI

• Production benchmarks and experiments

If you're interested in building AI systems that go beyond tutorial demos, consider subscribing.

👉 YouTube: Agentic Data Lab

Contributing

Issues, improvements and pull requests are welcome.

If you extend the MCP server with another useful GitHub analytics tool, feel free to open a PR.

Support the Project

If this repository helped you:

• ⭐ Star the repository

• 🍴 Fork it and build your own MCP tools

• ▶️ Subscribe to Agentic Data Lab

More production AI engineering projects are coming.