GitHub-MCP
Provides tools for interacting with the GitHub API, enabling repository management, issue and pull request tracking, developer profiling, and repository analytics.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@GitHub-MCP Compare the health of microsoft/vscode and facebook/react"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
GitHub-MCP π
A Production-Grade Model Context Protocol (MCP) Server for GitHub
2. Project Description
GitHub-MCP is an advanced, fully asynchronous Model Context Protocol (MCP) server that seamlessly bridges Claude Desktop (and other MCP clients) with the GitHub API. It goes beyond simple API wrapping by providing a sophisticated Intelligence Layer that generates deterministic, analytical insights into developers, repositories, issues, and pull requestsβwithout relying on secondary AI models or embeddings.
Related MCP server: gitbridge-mcp
3. Features
β¨ Seamless Integration: Native support for the MCP stdio transport.
π§ Developer Intelligence: Generate deep, deterministic profiles of developers based on their open-source footprint.
π Repository Analytics: Compare repositories, evaluate health scores, and receive tailored project recommendations.
π€ Collaboration Intelligence: Analyze issues and pull requests for code churn, complexity, and maintenance bottlenecks.
ποΈ Clean Architecture: Built on SOLID principles with strict separation between HTTP clients, business logic, and presentation layers.
β‘ High Performance: Fully asynchronous design leveraging asyncio.gather for concurrent API fetches, smartly capped to respect GitHub rate limits.
4. Why GitHub-MCP?
While Claude and other LLMs can browse the web or read raw JSON, providing them with pre-synthesized, strictly-typed analytical models drastically improves their contextual reasoning. GitHub-MCP mathematically calculates metrics like "Repository Health" and "Merge Complexity" so the LLM doesn't have to guess, resulting in faster, more accurate, and highly deterministic answers.
5. Architecture Overview
GitHub-MCP is built using a tiered architecture:
Presentation Layer (Tools): Exposes MCP functions and handles raw I/O.
Intelligence/Analysis Layer: Pure Python business logic. No HTTP requests, no LLMs.
Service Layer: Wraps raw API data into strongly-typed Pydantic domain models.
Client Layer: Manages
httpxasynchronous communication with GitHub, including dynamic 404 routing.
6. System Architecture Diagram
graph TD
Client[Claude Desktop] <-->|stdio / JSON-RPC| MCP[MCP Server Layer]
subgraph GitHub-MCP
MCP --> Tools[Tools Presentation]
Tools -->|Raw Data| Intel[Intelligence & Analysis Layer]
Intel -->|Synthesized Reports| Tools
Tools -->|Fetch Data| Service[GitHub Service]
Service -->|HTTP Requests| APIClient[GitHub Client]
end
APIClient <-->|REST| GitHub[GitHub API]7. Technology Stack
Language: Python 3.11+
Protocol:
mcp(v2.0.0)Validation:
pydantic(v2)HTTP Client:
httpxLinting & Formatting:
ruff
8. Project Structure
src/github_mcp/
βββ analysis/ # Developer Intelligence logic
βββ collaboration/ # Issues & PR Intelligence logic
βββ github/ # HTTP Client & Pydantic domain models
βββ intelligence/ # Repository Health & Recommendation logic
βββ tools/ # MCP Tool registration and presentation
βββ server.py # Application entry point and DI container9. Installation
Requires Python 3.11 or higher.
git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e .10. Configuration
Generate a GitHub Personal Access Token (PAT).
export GITHUB_TOKEN="github_pat_1234567890..."11. Running the MCP Server
You can run the server manually to verify it starts (it communicates via stdin/stdout, so you will see raw JSON-RPC if you type into it):
github-mcp12. Claude Desktop Configuration
Add the following to your Claude Desktop MCP configuration file (typically ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"github-mcp": {
"command": "/absolute/path/to/github-mcp/.venv/bin/github-mcp",
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}Restart Claude Desktop for the changes to take effect.
13. Available MCP Tools
GitHub-MCP exposes 15 highly specialized tools:
hello_world- Verify server connection.get_user_profile- Fetch raw user profile.list_user_repositories- List a user's repositories.get_repository- Fetch repository details.get_repository_languages- Fetch language bytes.analyze_developer- π§ Generate a developer intelligence report.compare_repositories- π Compare two repositories.repository_health- π Evaluate repository health out of 100.recommend_repositories- π Suggest new repositories based on stack.list_repository_issues- List open issues (excluding PRs).get_issue- Fetch specific issue details.list_pull_requests- List open pull requests.get_pull_request- Fetch specific PR details.analyze_issue- π€ Generate issue maintenance insights.analyze_pull_request- π€ Generate PR complexity insights.
14. Example Usage
In Claude Desktop, you can use natural language:
"Compare the repositories facebook/react and vuejs/core."
"Analyze the developer profile for octocat."
"What is the repository health of torvalds/linux?"
"Analyze issue #12 in octocat/Hello-World."
15. Sample Outputs
Repository Health Output:
Repository Health Report: octocat/Hello-World
Overall Score: 55/100
- Documentation: 15/30
- Metadata: 0/30
- Maintenance: 40/40
Strengths:
- Has a clear description
- Highly active maintenance
Weaknesses:
- No homepage or documentation link
- No explicit license16. Development Setup
git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"17. Running Tests
Testing is currently performed via bash script injection into the stdio transport. See docs/troubleshooting.md for manual testing instructions.
# Example
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | github-mcp18. Code Quality
We strictly enforce standard Python formatting using ruff.
python -m ruff check . --fix19. Future Roadmap
Additional Intelligence layers (e.g., Code Quality Analysis).
Pagination support for deeply traversing issues and PRs.
Automated
pytestsuite simulating JSON-RPC payloads.
20. Contributing
We welcome contributions! Please see our CONTRIBUTING.md for details on how to submit pull requests, our coding conventions, and our architectural constraints.
21. License
This project is licensed under the MIT License - see the LICENSE file for details.
22. Acknowledgements
Built using the official Model Context Protocol (MCP) Python SDK.
Powered by the robust GitHub REST API.
Available Tools
15 toolsanalyze_developerC
Perform a comprehensive, deterministic analysis on a GitHub developer's profile and repositories.
Args: username: The exact GitHub username to analyze.
Inputs: username (required). Returns: result
analyze_issueC
Perform a deterministic analysis on a GitHub Issue.
Inputs: repo (required), owner (required), issue_number (required). Returns: result
analyze_pull_requestC
Perform a deterministic analysis on a GitHub Pull Request.
Inputs: repo (required), owner (required), pull_number (required). Returns: result
compare_repositoriesA
Compare two GitHub repositories based on popularity, activity, and health.
Args: owner1: The owner of the first repository. repo1: The name of the first repository. owner2: The owner of the second repository. repo2: The name of the second repository.
Inputs: repo1 (required), repo2 (required), owner1 (required), owner2 (required). Returns: result
get_issueB
Get details for a specific issue.
Inputs: repo (required), owner (required), issue_number (required). Returns: result
get_pull_requestC
Get details for a specific pull request.
Inputs: repo (required), owner (required), pull_number (required). Returns: result
get_repositoryA
Fetch details for a specific repository.
Args: owner: The repository owner (username or organization). repo: The repository name.
Inputs: repo (required), owner (required). Returns: result
get_repository_languagesB
Fetch language statistics for a repository.
Args: owner: The repository owner. repo: The repository name.
Inputs: repo (required), owner (required). Returns: result
get_user_profileB
Fetch a user's GitHub profile.
Args: username: The exact GitHub username to look up.
Inputs: username (required). Returns: result
hello_worldA
A friendly greeting verifying GitHub-MCP is running.
Inputs: no named parameters. Returns: result
list_pull_requestsC
List pull requests for a repository.
Inputs: repo (required), owner (required). Returns: result
list_repository_issuesA
List open issues for a repository (excluding pull requests).
Args: owner: The repository owner. repo: The repository name.
Inputs: repo (required), owner (required). Returns: result
list_user_repositoriesB
Fetch a user's repositories.
Args: username: The exact GitHub username to look up.
Inputs: username (required). Returns: result
recommend_repositoriesA
Recommend new repositories to a developer based on their interests.
Args: username: The GitHub username to analyze.
Inputs: username (required). Returns: result
repository_healthB
Generate a repository health report with actionable recommendations.
Args: owner: The repository owner. repo: The repository name.
Inputs: repo (required), owner (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 15 tools
Each tool targets a distinct resource and action, but there is some potential confusion between analysis tools (e.g., analyze_issue vs get_issue) and retrieval tools. Overall, descriptions are clear enough to distinguish them.
Most tools follow a verb_noun pattern (get_, list_, analyze_, etc.), but 'hello_world' and 'repository_health' deviate from this convention. The naming is mostly consistent with minor exceptions.
With 15 tools, the server is at the upper edge of a well-scoped set. Each tool seems to serve a distinct purpose, though a few could potentially be consolidated without losing functionality.
The server provides good read and analysis operations for issues, PRs, repositories, and users, but lacks write operations like creating issues, merging PRs, or updating repositories. This limits its utility as a complete GitHub MCP server.
Related MCP Connectors
Create, deploy, and operate MCP servers directly from your GitHub repositories.
An MCP server that gives your AI access to the source code and docs of all public github repos
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives Claude Desktop complete intelligence about any public GitHub repository. Research libraries, compare packages, audit dependencies, and explore codebases through natural conversation.1MIT
- AlicenseNot gradedqualityCmaintenanceA production-ready MCP bridge server connecting Claude Chat to any GitHub repository for file operations, issue management, and code search via OAuth 2.0 authenticated Streamable HTTP transport.6MIT
- AlicenseBqualityDmaintenanceAn MCP server that enables managing GitHub repositories, pull requests, issues, and more through natural language in Cursor or Claude Desktop.3914 npm4MIT
- FlicenseNot gradedqualityDmaintenanceA working MCP server that connects to the real GitHub API, enabling users to manage repositories, issues, pull requests, and more through natural language in Claude Desktop.-