chayan-1906/GitHub-MCP

🐙 GitHub MCP Server

An MCP-compliant server built with TypeScript to extend Claude and other AI agents with superpowers for GitHub Repositories, Branches, Commits, Issues, Pull Requests, Releases, and Actions. Pre-built executables available for macOS, Windows, and Linux for easy end-user installation without Node.js dependencies.

⚙️ Quick Start

Option 1: Use Pre-built Package

1. Install Claude Desktop:

Download from https://claude.ai/download

2. Download the Executable:

macOS: 📦 Download macOS Executable

Windows: 📦 Download Windows Executable

3. Run the Executable:

• For macOS users:

  chmod +x github
  ./github
  

• For Windows users: Double-click the file, or run via terminal: .\github.exe

Note:

1. No need to run the executable repeatedly
2. Do NOT delete the executable after running
3. If you rename, move, or modify the executable, you must run it again (Step 3) to restart it properly

4. 🌐 Explore Available Tools (Optional)

Visit the homepage to browse all available tools:

• Homepage: http://localhost:20253/
• See all 44+ GitHub tools with user-friendly descriptions
• Great for understanding what the server can do

5. (Optional) Stop the Server:

You can stop the server if needed (launching Claude will automatically stop the currently running instance/port)

6. Launch Claude Desktop

Start Claude Desktop application

7. Start Asking Tasks:

Claude will now recognize the available tools with descriptions

Important: When prompting Claude, include "use available GitHub tools" in your prompts to ensure the LLM utilizes the GitHub MCP tools instead of defaulting to web search

Option 2: Build from Source

1. 📁 Clone the repo

git clone https://github.com/chayan-1906/GitHub-MCP.git
cd GitHub-MCP

2. 📦 Install dependencies

npm install

3. 🔧 Setup Configuration

Configure your credentials in src/config/config.ts:

export const PORT = 20253
export const DB_NAME = "github";
export const CLIENT_ID = "your_github_client_id"
export const CLIENT_SECRET = "your_github_client_secret"
export const GITHUB_CALLBACK_URL = `http://localhost:${PORT}/github/oauth/callback`
export const MONGODB_URI = "your_mongodb_connection_string"
export const TOKEN_SECRET = "your_token_secret"

Replace placeholder values with your actual GitHub OAuth app credentials and MongoDB connection string.

Generate a secure token secret:

openssl rand -hex 32

4. 🌐 Explore Available Tools

Visit the homepage to see all available tools with user-friendly descriptions:

• Homepage: http://localhost:20253/
• Browse all 44+ GitHub tools organized by category
• View user-friendly descriptions and use cases
• Perfect for understanding the server's capabilities

5. 🔧 Switch GitHub Accounts

To authenticate with a different GitHub account or refresh your session:

• Visit: http://localhost:20253/auth
• Complete OAuth flow with desired GitHub account

6. 🧪 Run the MCP Server

npm run dev

Or compile and run:

npm run build
npm run bundle
npm run package

📖 User Guide

Detailed documentation: GitHub MCP User Guide

🧰 Available Tools

📋 Changelog

v1.3.0 (2025-09-17)

🔄 Changes

• Routing System: Separated system and authentication routes for better code organization
  • Created dedicated SystemRoutes.ts for homepage functionality
  • Moved authentication endpoints to /auth prefix for cleaner URL structure
• Error Handling: Improved error reporting across all GitHub tool integrations
• Type Safety: Added ToolsMap interface for better TypeScript type definitions

📦 Dependencies

• axios: Updated from ^1.11.0 to ^1.12.2
• mongodb: Updated from ^6.18.0 to ^6.19.0
• uuid: Updated from ^11.1.0 to ^13.0.0
• @modelcontextprotocol/sdk: Updated from ^1.17.4 to ^1.18.0
• typescript: Updated from ^5.8.3 to ^5.9.2

🧹 Code Quality

• Removed Legacy Code: Eliminated toolHelpers.ts in favor of mcp-utils package integration
• Centralized Configuration: All tool definitions now use dynamic parameter descriptions
• Improved Maintainability: Better separation of concerns between system and authentication logic

v1.2.0 (2025-09-14)

✨ New Features

• Interactive Homepage: Complete tool browser at http://localhost:20253/ showcasing all 44+ GitHub MCP tools
• Tool Categorization: Organized tools by categories (Profile, Repositories, Branches, Issues, PRs, etc.) with modern glassmorphism UI
• Statistics Dashboard: Real-time stats showing tool counts, categories, and flexibility metrics
• Enhanced Authentication Flow: Redesigned success page with improved GitHub branding and mobile responsiveness

🔄 Changes

• Tool Architecture: Refactored tool constants to include structured metadata and categorization
• Parameter Descriptions: Enhanced user-friendly descriptions for better tool understanding
• Renamed tools: Renamed get-all-collaborators → list-collaborators, list-files-in-repository → repository-tree, get-all-releases → list-releases for consistency

📊 Statistics

• Total Tools: 44+ (organized across 9 categories)
• New Routes: Homepage (/) with comprehensive tool browser
• UI/UX: Modern responsive design with glassmorphism styling

v1.1.0 (2025-07-29)

✨ New Features

• Release Management Tools: Added complete GitHub release lifecycle management
  • list-releases - Paginated release listing with full metadata
  • create-release - Create releases from existing tags or new tags
  • update-release - Modify existing release information
  • delete-release - Remove releases (irreversible action)

🔄 Changes

• Renamed my-details → my-github-account for consistency

📊 Statistics

• Total Tools: 29 (increased from 25 in v1.0.0)
• New Category: Release management operations
• API Coverage: Extended GitHub REST API v4 support

v1.0.0 (2025-07-19)

🚀 Initial Release

• 25 GitHub API Tools for AI agents
• OAuth 2.0 Authentication with GitHub
• Repository Management - CRUD operations, visibility, collaboration
• Branch Operations - Create, delete, list, set default
• Issue Management - Create, update, assign, state changes
• File Operations - Read content, commit files, list repository tree
• Commit History - List commits, get modifications

🔧 Features

• 🔐 OAuth Authentication: Secure GitHub OAuth integration
• 📊 Repository Management: Complete CRUD operations for repositories
• 🌳 Branch Operations: Create, list, and manage branches
• 📝 Issue Tracking: Full issue lifecycle management
• 🔀 Pull Request Management: Create, review, merge, and manage pull requests
• 👥 Collaboration: Manage collaborators and permissions
• 📁 File Operations: Read, write, and commit files
• 🔄 Commit History: Access and analyze commit data
• 🚀 Release Management: Create and update releases
• ⚡ Real-time Updates: Live synchronization with GitHub API

🛠️ Architecture

The server is structured with:

• Tools: Individual GitHub operation handlers
• Services: OAuth and API management
• Utils: Helper functions and constants
• Types: TypeScript type definitions
• Config: Environment and configuration management

🔍 API Coverage

This MCP server provides comprehensive coverage of GitHub's REST API v4, including:

• Repository operations
• Branch management
• Issue tracking
• Pull request management
• File operations
• Collaboration features
• Commit history
• Release management
• User profile management

👨‍💻 Tech Stack

• 🟦 TypeScript – Type-safe application development
• 📄 GitHub API – GitHub integration and data access
• 🧠 MCP SDK – Model Context Protocol server framework
• ✅ Zod – Schema-based input validation
• 🔐 OAuth 2.0 – Secure authentication
• 📊 MongoDB – Data persistence
• 🚀 Express.js – Web server framework

🤝 Contributing

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

1. Fork the project
2. Create your feature branch (git checkout -b feature/add-github-discussions or git checkout -b fix/oauth-callback-error)
3. Commit your changes (git commit -m 'Add GitHub Discussions API support' or git commit -m 'Fix OAuth callback redirect issue')
4. Push to the branch (git push origin feature/add-github-discussions)
5. Open a Pull Request

👨‍💻 Author

Padmanabha Das

• GitHub: @chayan-1906
• LinkedIn: Padmanabha Das
• Email: padmanabhadas9647@gmail.com

🌟 Show Your Support

If this project helped you, please give it a ⭐️!

📱 Connect With Me

💡 Need More Tools?

If you need additional GitHub tools or features that aren't currently available, please let me know! I'm happy to extend the functionality based on your requirements

🔗 License

ISC