Skip to main content
Glama

GithubMCP

A Production-Grade Personal Developer Assistant MCP Server

License: MIT Python: 3.11+ Managed by: uv MCP Compatible Code style: ruff Type checked with: mypy

Seamlessly connect AI models (Claude, Cursor, etc.) to your GitHub workflows, CI/CD pipelines, local workspace context, and code analysis tools.


Overview

GithubMCP is a Model Context Protocol (MCP) server designed for developers. It bridges AI assistants directly with your development environment, enabling them to:

  • Inspect GitHub repositories, pull requests, issues, commits, and code across public and private repositories.

  • Manage repository privacy & visibility (public/private) directly through conversation.

  • Monitor CI/CD workflow runs and parse failed GitHub Actions build steps.

  • Inspect local filesystem workspaces safely within user-defined allowed paths.

  • Analyze code quality, calculate complexity metrics, find TODOs, and detect potential security smells (hardcoded secrets).

Supports both STDIO (Claude Desktop, Cursor) and SSE (Server-Sent Events for web clients) transport modes.


Related MCP server: GitHub Activity MCP Server

Tool Suite Reference

GithubMCP provides 17 specialized tools:

Category

Tool Name

Description

GitHub

search_repos

Search public & private user/org repositories with language & sort filters.

GitHub

inspect_pr

Fetch PR details, changed files, addition/deletion stats, and review comments.

GitHub

create_pull_request

Open a new pull request from head branch into base branch.

GitHub

create_branch

Create a new git branch in a repository off of an existing branch.

GitHub

create_or_update_file

Create or update and commit a file directly on a GitHub branch.

GitHub

create_issue

Open a new GitHub issue with title, body, labels, and assignees.

GitHub

inspect_issue

Inspect issue state, assignees, linked PRs, labels, and recent comments.

GitHub

search_code

Search code patterns across repositories with extension filters.

GitHub

recent_commits

Fetch recent commit history with diff statistics and authors.

GitHub

update_repo_visibility

Change repository visibility between private and public.

CI/CD

check_ci_status

Monitor GitHub Actions status (success/failure/in-progress) and failed step logs.

Filesystem

read_file

Read local file contents safely with MIME type detection and size validation.

Filesystem

list_directory

List directory tree structure with file sizes, mtime, and glob filters.

Filesystem

search_local_files

Asynchronously grep files for regex/patterns with surrounding line context.

Filesystem

get_project_context

Detect project tech stack (Node, Python, Rust, Go, Docker) & dev commands.

Analysis

generate_change_summary

Compare git refs and categorize commits into Features, Fixes, Breaking Changes, etc.

Analysis

analyze_code_quality

Compute lines of code, complexity estimate, TODO comments, and secret smells.


Quick Start

1. Prerequisites

  • Python 3.11+

  • uv (Fast Python package manager)

Install uv (if not already installed):

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone & Setup

git clone https://github.com/Dhananjayrbiraris/github-mcp.git
cd github-mcp

# Install dependencies and sync virtual environment
uv sync

3. Environment Configuration

Copy the template .env.example to .env:

cp .env.example .env

Edit .env with your GitHub Personal Access Token:

# GitHub Personal Access Token (Classic PAT with 'repo', 'workflow', 'read:user' scopes)
GITHUB_TOKEN=ghp_your_github_token_here

# Default GitHub Username (Optional)
GITHUB_USERNAME=your_username

# Sandboxed directories allowed for local filesystem operations
ALLOWED_PATHS=["~/projects", "~/workspace", "."]

# Max file size limit in MB for reading files
MAX_FILE_SIZE_MB=10

# Default Transport mode: "stdio" or "sse"
TRANSPORT=stdio

Generating your GitHub Token: Go to GitHub Settings -> Developer Settings -> Personal access tokens (classic) and generate a token with repo, workflow, and read:user scopes.


Client Setup Guides

A. Claude Desktop

1. Open the Claude Desktop configuration file:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add the github-mcp server:

{
  "mcpServers": {
    "github-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/github-mcp",
        "run",
        "python",
        "-m",
        "github_mcp.main",
        "--transport",
        "stdio"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token_here"
      }
    }
  }
}

(On Windows, use backslashes e.g. C:\\Users\\yourname\\path\\to\\github-mcp or forward slashes).

3. Restart Claude Desktop

Open Claude Desktop — click the Tools icon at the bottom right of the prompt box to view all connected GithubMCP tools.


B. Cursor IDE

In Cursor:

  1. Navigate to Cursor Settings -> Features -> MCP.

  2. Click + Add New MCP Server.

  3. Fill in:

    • Name: github-mcp

    • Type: command

    • Command: uv --directory /path/to/github-mcp run python -m github_mcp.main --transport stdio


C. Server-Sent Events (SSE) Mode / Web Clients

To run the MCP server over HTTP / Server-Sent Events:

uv run python -m github_mcp.main --transport sse --host 0.0.0.0 --port 8000

SSE endpoint will be available at: http://localhost:8000/sse


Security & Sandboxing

  1. Path Sandboxing: Local filesystem tools (read_file, list_directory, search_local_files, get_project_context) strictly enforce path traversal validation against ALLOWED_PATHS. Accessing paths outside the allowlist will raise a SecurityError.

  2. Secret Management: Tokens and credentials are never logged or exposed.

  3. Rate Limit Resilience: Automatic exponential backoff retries on GitHub API rate limit throttling.


Development & Testing

Run the full testing and quality check suite:

# Run pytest unit tests
uv run pytest

# Run linter
uv run ruff check .

# Check code formatting
uv run ruff format --check .

# Run strict type checking
uv run mypy src/

Repository Structure

github-mcp/
├── .github/workflows/ci.yml # GitHub Actions CI workflow
├── src/github_mcp/
│   ├── __init__.py
│   ├── main.py              # Server entrypoint & MCP tool registrations
│   ├── config.py            # Pydantic Settings model
│   ├── github_tools.py      # GitHub API integrations & visibility controls
│   ├── file_tools.py        # Sandboxed local filesystem operations
│   ├── ci_tools.py          # GitHub Actions CI/CD monitoring
│   ├── analysis_tools.py    # Diff categorization & code quality analyzer
│   └── utils.py             # Path safety, error handling, rate limiting
├── tests/
│   ├── conftest.py          # Pytest fixtures and mocks
│   ├── test_github.py       # GitHub tools unit tests
│   ├── test_files.py        # Filesystem tools unit tests
│   └── test_ci.py           # CI status tools unit tests
├── docs/
│   ├── architecture.md      # System architecture & data flow
│   └── tools_reference.md   # Complete API schemas for all 13 tools
├── pyproject.toml           # Project dependencies & tool configurations
├── .env.example             # Environment variable template
├── CONTRIBUTING.md          # Open-source contribution guidelines
├── SECURITY.md              # Security policy & vulnerability reporting
└── LICENSE                  # MIT License

License

This project is licensed under the MIT License — free for personal and commercial use.


Available Tools

13 tools
analyze_code_qualityA

Analyze file metrics (line counts, comment ratio, complexity estimate), TODO/FIXME comments, and potential security smells (hardcoded secrets).

Inputs: path (required). Returns: object

check_ci_statusA

Check current build status (success/failure/in_progress), duration, log URL, and summary of failed steps for GitHub Actions.

Inputs: repo (required), branch, platform. Returns: object

generate_change_summaryA

Compare base and head git refs for a repository and generate a human-readable summary categorized by Features, Fixes, Breaking Changes, and Config Updates.

Inputs: repo (required), base_ref (required), head_ref (required). Returns: object

get_project_contextB

Detect project type (Node, Python, Rust, Go, Docker), key config files, sample dependencies, and suggested dev commands.

Inputs: root_path (required). Returns: object

inspect_issueA

Fetch issue details including assignees, state, labels, linked PRs, and recent comments.

Inputs: repo (required), issue_number (required). Returns: object

inspect_prA

Fetch pull request details including changed files, diff stats, additions/deletions, and review comments.

Inputs: repo (required), pr_number (required). Returns: object

list_directoryB

List directory structure, files, subdirectories, sizes, and modification dates with optional depth limit and glob filter.

Inputs: path (required), recursive, depth_limit, glob_pattern. Returns: object

read_fileA

Read file contents securely within allowed directories with MIME type detection and size validation.

Inputs: path (required). Returns: object

recent_commitsA

Fetch recent commits for a repository branch within lookback days with commit stats.

Inputs: repo (required), days, limit, branch. Returns: result

search_codeA

Search code across specified repositories matching pattern and optional file extension filter.

Inputs: repos (required), pattern (required), file_extension. Returns: result

search_local_filesA

Search local directory files for text matching pattern with line numbers and surrounding context.

Inputs: path (required), pattern (required), file_type, case_sensitive. Returns: result

search_reposA

Search GitHub repositories matching query, optional language filter, and sort order.

Inputs: sort, limit, query, language. Returns: result

update_repo_visibilityA

Update the privacy/visibility settings of a repository to make it private or public.

Inputs: repo (required), private (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: repository search, code search, local file search, PR/issue inspection, CI status, and file analysis are clearly separated. The three search tools differ by target, and read/list/analyze local tools have unambiguous boundaries.

    Naming Consistency4/5

    Most tools follow a verb_noun snake_case pattern like search_repos, inspect_pr, read_file, and update_repo_visibility. The main inconsistency is recent_commits, which uses adjectival naming rather than an imperative verb, and get_project_context breaks the simple verb-noun pattern slightly.

    Tool Count5/5

    13 tools is a well-scoped count for the apparent purpose of reading and analyzing GitHub repositories alongside local project inspection. Every tool has a clear, non-redundant job and the set feels dense without being bloated.

    Completeness3/5

    There is strong coverage for inspecting and analyzing repos, PRs, issues, CI, and local code, and generate_change_summary provides a useful diff workflow. However, as a GitHub MCP server it lacks list/create/update operations for PRs and issues, forcing agents to know IDs in advance and making common collaborative workflows impossible.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to inspect local Git repositories and interact with the GitHub API for reading commits, diffs, files, issues, comments, pull requests, and project boards.
      10
      133 npm
      ISC
    • A
      license
      A
      quality
      C
      maintenance
      Connects LLMs and AI agents directly to GitHub repositories, enabling repository inspection, file and tree exploration, code search, commit history, issues, pull requests, and releases for both public and private repos.
      13
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables AI coding assistants to inspect local and remote repositories through sandboxed tools that surface project overviews, structure, dependency audits, Git churn hotspots, and a heuristic health score. It also supports safe GitHub issue searching and creation with built-in duplicate preflight checks, while blocking sensitive files, binary content, and path traversal attacks.
      22 npm
      MIT