🐙 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

🛠️ Installation

Quick Start

npm install -g 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: [email protected]
• 🐙 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