GitHub-MCP 🚀

A Production-Grade Model Context Protocol (MCP) Server for GitHub

Python MCP License Code style: ruff

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.

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 httpx asynchronous 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: httpx
Linting & 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 container

9. 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-mcp

12. 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 license

16. 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-mcp

18. Code Quality

We strictly enforce standard Python formatting using ruff.

python -m ruff check . --fix

19. Future Roadmap

Additional Intelligence layers (e.g., Code Quality Analysis).
Pagination support for deeply traversing issues and PRs.
Automated pytest suite 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.