🐙 GitHub MCP Server

A powerful Model Context Protocol (MCP) server that enables AI assistants to analyze and read GitHub repositories with ease. Perfect for code analysis, repository exploration, and understanding project structures.

✨ Features

🔍 Repository Structure Analysis

• Complete directory traversal with configurable depth

• File type distribution analysis and statistics

• Project architecture insights with framework detection

• Important file detection (README, package.json, Dockerfile, etc.)

• Visual tree structure representation

• Size analysis and file counting

📖 File Content Reading

• Multi-format support (UTF-8, Base64, Raw)

• Syntax highlighting for 30+ programming languages

• Code analysis with function/class counting

• Pattern detection (TODO comments, async/await, etc.)

• Smart content truncation for large files

• Binary file handling with appropriate encoding

🚀 Advanced Capabilities

• Rate limit optimization with GitHub token support

• Branch-specific analysis (main, develop, feature branches)

• Error handling with detailed troubleshooting

• Session management for efficient API usage

• Streamable HTTP transport for modern AI clients

Related MCP server: GitHub Repo Explainer MCP

🛠️ Installation

Quick Start

npm install -g @xingyuchen/github-mcp-server

From Source

git clone https://github.com/guangxiangdebizi/github-mcp-server.git
cd github-mcp-server
npm install
npm run build

⚙️ Configuration

Environment Setup

1. Copy environment template:

   cp .env.example .env

2. Configure your settings:

   # GitHub Personal Access Token (recommended for higher rate limits)
   GITHUB_TOKEN=your_github_token_here
   
   # Server Configuration
   PORT=3000
   
   # Optional: Default repository
   DEFAULT_REPO=owner/repository

GitHub Token Setup

For optimal performance and access to private repositories:

1. Go to GitHub Settings > Developer settings > Personal access tokens

2. Generate a new token with repo scope

3. Add it to your .env file

🚀 Usage

Starting the Server

# Production mode
npm start

# Development mode
npm run dev

# HTTP mode (recommended)
npm run start:http

The server will start at http://localhost:3000 with the MCP endpoint at /mcp.

Client Configuration

Add to your AI client's MCP configuration:

{
  "mcpServers": {
    "github-analyzer": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}

🔧 Available Tools

1. analyze_repository_structure

Analyze the complete structure and architecture of a GitHub repository.

Parameters:

• owner (required): Repository owner/organization

• repo (required): Repository name

• path (optional): Specific directory to analyze

• branch (optional): Branch name (default: main)

• max_depth (optional): Maximum traversal depth (1-5, default: 3)

Example:

{
  "owner": "microsoft",
  "repo": "vscode",
  "branch": "main",
  "max_depth": 3
}

2. read_repository_file

Read and analyze the contents of a specific file from a GitHub repository.

Parameters:

• owner (required): Repository owner/organization

• repo (required): Repository name

• path (required): File path within the repository

• branch (optional): Branch name (default: main)

• encoding (optional): File encoding (utf8/base64/raw, default: utf8)

• max_size (optional): Maximum file size in bytes (default: 1MB, max: 5MB)

Example:

{
  "owner": "microsoft",
  "repo": "vscode",
  "path": "src/vs/code/electron-main/main.ts",
  "branch": "main"
}

📊 Example Output

Repository Structure Analysis

# 📊 Repository Structure Analysis

## 📋 Repository Information
- **Repository:** microsoft/vscode
- **Description:** Visual Studio Code
- **Language:** TypeScript
- **Stars:** 150,000 ⭐
- **Forks:** 25,000 🍴

## 📁 Directory Structure
📁 src/
  📁 vs/
    📄 main.ts (15.2 KB)
    📁 workbench/
      📄 workbench.main.ts (8.5 KB)

## 📈 Statistics
- **Total Files:** 12,450
- **Total Directories:** 1,200
- **Total Size:** 145.2 MB

## 🏗️ Project Architecture Insights
🟨 **TypeScript Project** - Modern web development stack detected
📦 **Node.js Ecosystem** - Uses npm package management
🐳 **Containerized** - Docker deployment ready

File Content Analysis

# 📄 File Content Analysis

## 📋 File Information
- **Repository:** microsoft/vscode
- **File Path:** `src/main.ts`
- **Branch:** main

## 📊 Content Analysis
**File Type:** TypeScript
**Size:** 15.2 KB
**Lines:** 450
**Functions:** 12
**Classes:** 3
**Imports:** 25

## 📝 File Content
```typescript
import { app, BrowserWindow } from 'electron';
// ... (file content with syntax highlighting)

🔍 Health Check

Monitor server status:

curl http://localhost:3000/health

Response:

{
  "status": "healthy",
  "transport": "streamable-http",
  "activeSessions": 2,
  "serverInfo": {
    "name": "GitHub-MCP",
    "version": "1.0.0"
  }
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/AmazingFeature)

3. Commit your changes (git commit -m 'Add some AmazingFeature')

4. Push to the branch (git push origin feature/AmazingFeature)

5. Open a Pull Request

📝 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👨‍💻 Author

Xingyu Chen

• 🌐 LinkedIn: Xingyu Chen

• 📧 Email: guangxiangdebizi@gmail.com

• 🐙 GitHub: @guangxiangdebizi

• 📦 NPM: @xingyuchen

🙏 Acknowledgments

• Built with the Model Context Protocol SDK

• Powered by GitHub REST API

• Inspired by the need for better AI-repository integration