🐙 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

Tool Name	Category	Description
my-github-account	Profile	Retrieves details of the authenticated GitHub user, including username, display name, email (if available), avatar URL, and profile link
list-repositories	Repositories	Fetches repositories user has access to. Calls repeatedly with increasing currentPage until result is empty
get-repository-details	Repositories	Fetches metadata of a GitHub repository (e.g., default branch, visibility, description, etc.). Useful before accessing files or commits from a repo
create-repository	Repositories	Creates a new GitHub repository for the authenticated user with optional description, visibility, and initialization
update-repository	Repositories	Updates repository description and/or tags (topics) of a GitHub repository
rename-repository	Repositories	Renames a GitHub repository owned by the authenticated user
delete-repository	Repositories	Deletes a GitHub repository owned by the authenticated user. This action is irreversible
modify-repository-visibility	Repositories	Modifies a GitHub repository visibility (private/public/internal)
list-collaborators	Repositories	Returns a combined list of accepted collaborators and pending invitations for a GitHub Repository, each marked with their status
add-remove-collaborators	Repositories	Adds or removes a collaborator from a GitHub repository
list-branches	Branches	Fetches branches of the authenticated user's repository. Calls repeatedly with increasing currentPage until the result is empty
get-branch-details	Branches	Fetches details of a specific branch in a GitHub repository
create-branch	Branches	Creates a new branch from a given commit SHA (usually the latest commit of an existing branch)
set-default-branch	Branches	Sets the default branch in a GitHub repository
delete-branch	Branches	Deletes a branch from a GitHub repository. Cannot delete the default branch
repository-tree	Files	Displays the hierarchical tree structure of a GitHub repository branch with ASCII tree formatting. Shows files and directories in a visual tree layout with filtering and pagination support.
get-file-content	Files	Reads and returns the raw content of a specific file from a GitHub repository branch
commit-remote-file	Files	Commits a file to a GitHub Repository using GitHub API. This does not use the local file system. • parentCommitSha & baseTreeSha: must be real SHAs. • If the repository is empty, omit these fields (don't pass 000…000).
list-commits	Commits	Fetches commits in a branch of a GitHub repository, page by page
get-commit-modifications	Commits	Returns the list of files modified in a specific GitHub commit
list-issues	Issues	Fetches issues from a GitHub repository, page by page. Calls repeatedly with increasing currentPage until result is empty
get-issue-details	Issues	Fetches detailed information about a specific GitHub issue by issue number
get-issue-comments	Issues	Fetches all comments for a GitHub issue, including the original issue, all comments, and participant details. Automatically fetches all pages of comments
create-issue	Issues	Creates a new issue in a GitHub repository. Including body and labels is optional
update-issue	Issues	Updates the title, body, and/or labels of an existing GitHub issue. Also works for pull requests since PRs are treated as issues for label management.
update-issue-state	Issues	Updates the state of a GitHub issue (open or closed) by issue number
assign-issue	Issues	Assigns one or more GitHub users to a GitHub issue
list-pull-requests	Pull Requests	Fetches all pull requests from a GitHub repository, page by page. Filter by state and sort options available
get-pull-request-details	Pull Requests	Fetches detailed information about a specific GitHub pull request by PR number
create-pull-request	Pull Requests	Creates a new pull request in a GitHub repository. Compares changes between two branches and creates a PR for review
update-pull-request	Pull Requests	Updates title, body, state, and base branch of an existing pull request
list-pull-request-commits	Pull Requests	Lists all commits in a specific pull request with pagination support
list-pull-request-files	Pull Requests	Lists all files changed in a specific pull request with diff information
update-pull-request-state	Pull Requests	Updates the state of a pull request (open or closed)
merge-pull-request	Pull Requests	Merges a GitHub pull request only if PR is open, not draft, and has no conflicts
get-pull-request-reviews	Pull Requests	Lists all reviews for a specific GitHub pull request, page by page
create-pull-request-review	Pull Requests	Creates a review for a GitHub pull request. Can approve, request changes, or add comments
request-pull-request-review	Pull Requests	Requests reviews from users and/or teams for a GitHub pull request
dismiss-pull-request-review	Pull Requests	Dismisses a pull request review with a message explaining why it was dismissed
mark-pull-request-review	Pull Requests	Submits a pending pull request review by marking it with APPROVE, REQUEST_CHANGES, or COMMENT
list-releases	Releases	Fetches all releases in a GitHub repository, page by page
create-release	Releases	Creates a GitHub release from an existing tag or creates a new tag and release
update-release	Releases	Updates an existing GitHub release by release ID with new information
delete-release	Releases	Deletes a GitHub release by release ID. This action is irreversible

---

📋 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

MIT

---

Made with ❤️ by Padmanabha Das

⭐ Star this repo if you found it helpful!

Note: This server requires GitHub OAuth authentication. Please ensure you have proper credentials configured before running.