GitHub MCP Server

# 🐙 GitHub MCP Server [](https://badge.fury.io/js/@xingyuchen%2Fgithub-mcp-server) [](https://opensource.org/licenses/Apache-2.0) [](https://nodejs.org/) 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 ```bash npm install -g @xingyuchen/github-mcp-server ``` ### From Source ```bash 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:** ```bash cp .env.example .env ``` 2. **Configure your settings:** ```env # 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](https://github.com/settings/tokens) 2. Generate a new token with `repo` scope 3. Add it to your `.env` file ## 🚀 Usage ### Starting the Server ```bash # 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: ```json { "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:** ```json { "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:** ```json { "owner": "microsoft", "repo": "vscode", "path": "src/vs/code/electron-main/main.ts", "branch": "main" } ``` ## 📊 Example Output ### Repository Structure Analysis ```markdown # 📊 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 ```markdown # 📄 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: ```bash curl http://localhost:3000/health ``` Response: ```json { "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](LICENSE) file for details. ## 👨‍💻 Author **Xingyu Chen** - 🌐 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/) - 📧 Email: guangxiangdebizi@gmail.com - 🐙 GitHub: [@guangxiangdebizi](https://github.com/guangxiangdebizi/) - 📦 NPM: [@xingyuchen](https://www.npmjs.com/~xingyuchen) ## 🙏 Acknowledgments - Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk) - Powered by [GitHub REST API](https://docs.github.com/en/rest) - Inspired by the need for better AI-repository integration --- <div align="center"> <strong>⭐ Star this repository if you find it helpful! ⭐</strong> </div>