GitHub MCP Server

🐙 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 @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

Copy environment template:
cp .env.example .env
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:

Go to GitHub Settings > Developer settings > Personal access tokens
Generate a new token with repo scope
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.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
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

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Enables AI assistants to analyze GitHub repository structures and read file contents with features like directory traversal, file type analysis, syntax highlighting, and code pattern detection. Supports both public and private repositories through GitHub API integration.

Related MCP Servers

GitHub Mapper MCP Server
dazeb
A
security
F
license
A
quality
Provides tools for mapping and analyzing GitHub repositories. It allows users to set a GitHub Personal Access Token and retrieve detailed information about a specified repository, including its structure and summary statistics.
Last updated -
2
18
OSSInsight MCP Server
damonxue
A
security
A
license
A
quality
Provides GitHub data analysis for repositories, developers, and organizations, enabling insights into open source ecosystems through API calls and natural language queries.
Last updated -
5
13
MIT License
GitHub Enterprise MCP Server
piyushgIITian
-
security
A
license
-
quality
Enables interaction with GitHub repositories through the GitHub API, allowing file operations, repository management, issue tracking, and code search through natural language commands.
Last updated -
10
2
MIT License
GitHub MCP Tools
Pranesh-2005
-
security
F
license
-
quality
A set of tools allowing AI assistants to interact directly with GitHub, enabling automation of tasks like fetching user profiles, creating repositories, and managing pull requests.
Last updated -

View all related MCP servers

GitHub MCP Server