Skip to main content
Glama

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.

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 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:

  1. hello_world - Verify server connection.

  2. get_user_profile - Fetch raw user profile.

  3. list_user_repositories - List a user's repositories.

  4. get_repository - Fetch repository details.

  5. get_repository_languages - Fetch language bytes.

  6. analyze_developer - 🧠 Generate a developer intelligence report.

  7. compare_repositories - πŸ“Š Compare two repositories.

  8. repository_health - πŸ“Š Evaluate repository health out of 100.

  9. recommend_repositories - πŸ“Š Suggest new repositories based on stack.

  10. list_repository_issues - List open issues (excluding PRs).

  11. get_issue - Fetch specific issue details.

  12. list_pull_requests - List open pull requests.

  13. get_pull_request - Fetch specific PR details.

  14. analyze_issue - 🀝 Generate issue maintenance insights.

  15. 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

Available Tools

15 tools
analyze_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

    B3.1/5.0

    Scored across 15 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count4/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      An 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.
      1
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      A 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.
      6
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A 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.
      -