🐙 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

From Source

⚙️ 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

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

Client Configuration

Add to your AI client's MCP configuration:

🔧 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:

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:

📊 Example Output

Repository Structure Analysis

File Content Analysis

🔍 Health Check

Monitor server status:

Response:

🤝 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