🔍 GitHub Insights MCP Server

An MCP (Model Context Protocol) server that lets Claude understand any public GitHub repository — its purpose, structure, tech stack, and architecture — by exposing typed, focused tools instead of requiring manual browsing.

Built to explore the MCP protocol: tool design, structured data contracts, and the division of labor between a tool-providing server and the LLM client that consumes it.

Table of Contents

• How it Works

• Architecture

• Tech Stack

• Project Structure

• Getting Started

• Connecting to Claude Desktop

• Running Tests

• Design Decisions

• Known Limitations

• Roadmap

Related MCP server: GitHub Context MCP Server

How it Works

Ask Claude Desktop about any public GitHub repo, and it can call one of five tools:

• get_repo_overview_tool — metadata (stars, language, last update) + README content

• get_repo_structure_tool — depth-limited file/folder tree

• get_tech_stack_tool — detected languages and dependency manifest files

• generate_architecture_diagram_tool — a Mermaid diagram of the top-level structure

• get_file_content_tool — full content of a specific file, for deeper analysis

Claude decides which tools to call and in what order based on the question — e.g. reading get_repo_structure_tool's output to identify an entry point file, then calling get_file_content_tool to actually read it.

Architecture

┌─────────────────┐     stdio (MCP/JSON-RPC)    ┌──────────────────────┐
│  Claude Desktop   │ ──────────────────────────▶ │  GitHub Insights MCP  │
│  (MCP client)      │ ◀────────────────────────── │       Server           │
└─────────────────┘                              └───────────┬──────────┘
                                                               │ HTTPS (REST)
                                                               ▼
                                                    ┌──────────────────┐
                                                    │   GitHub API       │
                                                    └──────────────────┘

The server runs locally as a subprocess launched by Claude Desktop, communicating over stdio using the MCP protocol. It never talks to an LLM itself — it fetches and structures data from the GitHub REST API, and lets the calling LLM (Claude) handle summarization and reasoning. See Design Decisions for why this split matters.

Tech Stack

Project Structure

github-insights-mcp/
├── server.py                  # MCP entrypoint - registers tools, starts stdio transport
├── github_client.py            # Sole GitHub REST API access layer (auth, retries, error mapping)
├── analyzers/
│   ├── overview.py               # Repo metadata + README content
│   ├── structure.py               # Depth-limited file/folder tree
│   ├── tech_stack.py               # Language + manifest file detection
│   ├── diagram.py                   # Mermaid diagram generation (pure function)
│   └── file_content.py               # Single-file content retrieval
├── tests/
│   ├── conftest.py                 # Shared fixtures
│   ├── test_github_client.py        # URL parsing, HTTP error mapping (mocked)
│   ├── test_tech_stack.py            # Detection logic (mocked)
│   └── test_diagram.py                # Diagram generation (pure, unmocked)
├── models.py                    # Pydantic models for every tool's input/output
├── config.py                     # Validated settings, absolute .env resolution
├── logging_config.py              # Logging setup (stderr, not stdout — see below)
├── exceptions.py                   # Domain-specific exception types
├── docs/
│   ├── PRD.md                        # Product requirements
│   └── ARCHITECTURE.md                # Technical design
├── requirements.txt
├── pytest.ini
└── .env.example

Getting Started

Prerequisites

• Python 3.11+

• A GitHub Personal Access Token with public_repo scope only (create one here)

• Claude Desktop (free to install; no paid plan required for local MCP servers)

Setup

git clone https://github.com/AhmetSOGUT/github-insights-mcp.git
cd github-insights-mcp

conda create -n github-insights-mcp python=3.11 -y
conda activate github-insights-mcp

pip install -r requirements.txt

cp .env.example .env
# edit .env and set GITHUB_TOKEN=your-token-here

Connecting to Claude Desktop

1. Open Claude Desktop → Settings → Developer → Edit Config

2. Add this server under mcpServers (create the key if it doesn't exist):

{
  "mcpServers": {
    "github-insights": {
      "command": "/absolute/path/to/your/python",
      "args": ["/absolute/path/to/github-insights-mcp/server.py"]
    }
  }
}

Use the absolute path to the Python interpreter inside your conda environment (where python on Windows / which python on macOS/Linux) — Claude Desktop does not inherit your shell's activated environment.

3. Restart Claude Desktop completely (quit from the system tray, not just close the window).

4. Check Settings → Connectors — github-insights should show as connected.

5. Ask Claude something like: "Summarize what this repo does: https://github.com/owner/repo"

Running Tests

All GitHub API calls are mocked via respx — no token or network access needed to run the suite:

pytest -v

Design Decisions

• Why does the server not summarize anything itself? It returns structured, factual data (README text, file contents, metadata) and leaves synthesis to the calling LLM. Calling a second LLM from inside the server would mean a second API key, doubled latency, and duplicated work the client is already positioned to do. This keeps the server a pure tool provider, in line with what MCP is designed for.

• Why log to stderr instead of stdout? MCP communicates with its client over stdout. Anything else written to stdout — including log output — would corrupt the protocol stream and break the connection. All logging in this project is explicitly routed to stderr.

• Why resolve .env via an absolute path in config.py? Claude Desktop launches this server from an unpredictable working directory (not necessarily the project root). A relative .env path works when run manually from the project folder but fails silently under Claude Desktop, causing confusing startup failures. Resolving the path via Path(__file__).parent makes config loading independent of how the process was launched.

• Why a single GitHubClient instead of calling httpx directly from each analyzer? Authentication, retry behavior, and GitHub-specific error translation (404 → RepoNotFoundError, rate-limited 403 → RateLimitError) live in exactly one place. Analyzers stay focused on interpreting data, not on HTTP or auth concerns.

Known Limitations

• README and file content are truncated (README to ~3,000 characters, individual files to 50,000 characters) to keep responses fast and token-efficient. For very large files or sparse READMEs, this can produce a less complete picture than Claude's own web browsing would, which has no such caps — this is a deliberate v1 trade-off, not an oversight (see docs/PRD.md, Section 4).

• The architecture diagram only reflects top-level folders, not actual import relationships between files. A more accurate diagram would require parsing source files, which is out of scope for v1.

• Single-user, PAT-based auth only. Anyone using this server needs their own GitHub token; there's no OAuth flow for a shared/hosted deployment.

Roadmap

• Deeper architecture diagrams based on actual import/dependency parsing

• OAuth-based auth for a shared, multi-user deployment

• Commit/PR/issue activity summaries

• Smarter file selection (auto-detect entry points to read, rather than requiring the LLM to guess a path)

• A remote-hosted version of the server

License

MIT