Skip to main content
Glama

github-mcp

Tests PyPI version Python License: MIT

GitHub MCP server for Claude Code, Cursor, Cline, Windsurf, and any MCP-compatible client.

Exposes GitHub tools (issues, pull requests, code search, file content) to your LLM via the Model Context Protocol.

Features

  • ๐Ÿ” Connection pooling & retry โ€” single HTTP client per process, exponential backoff on 429/5xx, honors Retry-After.

  • ๐Ÿ›ก๏ธ Typed errors โ€” GitHubError carries HTTP status, parsed message, and endpoint.

  • โœ… Input validation โ€” catches bad inputs before the network round-trip.

  • ๐Ÿ“„ Text files decoded โ€” get_file_content returns UTF-8 text under decoded_content for text files.

  • ๐Ÿงช Fully tested โ€” 75 mock-based tests, plus opt-in live integration tests.

  • ๐Ÿชถ Tiny โ€” three runtime deps (mcp, httpx, pydantic); no PyGithub.

Related MCP server: GitHub MCP Agent Server

Tools exposed

Tool

Description

list_issues

List issues (filter by state, labels, since) โ€” PRs filtered out

get_issue

Get a single issue by number

create_issue

Create an issue (with optional labels)

list_pull_requests

List PRs (filter by state)

get_pull_request

Get a single PR by number

search_code

Search code across GitHub (requires code-search scope)

get_file_content

Read a file at a ref; text files returned UTF-8-decoded

Full parameter docs: docs/USAGE.md.

Install

pip install github-mcp

Or with uv:

uv tool install github-mcp

Requires Python 3.10+.

Authenticate

  1. Create a GitHub personal access token:

  2. Set the token:

    export GITHUB_TOKEN="ghp_..."   # macOS / Linux / Git Bash
    # or PowerShell: $env:GITHUB_TOKEN = "ghp_..."

    See docs/AUTH.md for Windows and per-client config.

Configure your client

Claude Code

claude mcp add --transport stdio github -- github-mcp

Cursor

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "github": {
      "command": "github-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_..."
      }
    }
  }
}

Cline / Windsurf

See your client's docs for adding a stdio MCP server. Command: github-mcp. Env: GITHUB_TOKEN.

Example prompts

"List the 5 most recent open issues in cli/cli labeled bug."

"Get issue #1234 in cli/cli and summarize the discussion."

"Create a new issue in my-org/my-repo titled Bug: login fails on Safari with body Steps to reproduce: ...."

"Show me the contents of src/main.py in cli/cli on the main branch."

"Search GitHub for function authenticate in cli/cli."

Development

git clone https://github.com/AbdeeBuilds/github-mcp
cd github-mcp
python -m venv .venv
source .venv/Scripts/activate   # Git Bash on Windows
pip install -e ".[dev]"
pytest                          # mock-based suite
GITHUB_TOKEN=*** pytest tests/test_live.py -v   # live integration

Quality gates (run on every PR):

ruff check src tests
ruff format --check src tests
mypy src

License

MIT โ€” see LICENSE.

Available Tools

7 tools
create_issueA

Create a new issue in a GitHub repository you have write access to.

Inputs: repo (required), owner (required), title (required), body, +1 more.

get_file_contentA

Read the contents of a file from a GitHub repository at a given ref (branch, tag, or commit SHA). Defaults to the repo's default branch. Text files are returned UTF-8-decoded under 'decoded_content'.

Inputs: path (required), repo (required), owner (required), ref.

get_issueA

Get a single GitHub issue by its number.

Inputs: repo (required), owner (required), number (required).

get_pull_requestA

Get a single GitHub pull request by its number.

Inputs: repo (required), owner (required), number (required).

list_issuesA

List issues in a GitHub repository. Returns the most recent issues in the specified state. Pull requests are filtered out.

Inputs: repo (required), owner (required), limit, since, +2 more.

list_pull_requestsB

List pull requests in a GitHub repository.

Inputs: repo (required), owner (required), limit, state.

search_codeA

Search for code across GitHub repos. Requires a fine-grained token with 'Code: Read' scope, or a classic token with repo scope.

Inputs: query (required), limit.

Tool Schema Changelog

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

Loading tool schema changelogโ€ฆ

    TDQS

    A3.8/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct GitHub resource (issues, pull requests, files, code search) with clear boundaries. No two tools could be confused for the same task.

    Naming Consistency5/5

    All tool names follow the verb_noun pattern in snake_case (e.g., create_issue, list_pull_requests, search_code), providing a predictable and uniform naming convention.

    Tool Count5/5

    With 7 tools, the server is well-scoped for basic GitHub interactions. The number is neither too sparse nor excessive for its purpose.

    Completeness2/5

    The tool set is missing fundamental operations like update and delete for issues and pull requests, and lacks the ability to create pull requests. This creates significant gaps that hinder common workflows.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that allows Claude and other MCP-compatible LLMs to interact with the GitHub API, supporting features like creating issues, getting repository information, listing issues, and searching repositories.
      4
      ISC
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol (MCP) server that connects Claude AI directly to the GitHub API, enabling natural language queries for live repository data, issues, PRs, and contributions.
      1
      -
    • A
      license
      B
      quality
      D
      maintenance
      MCP (Model Context Protocol) server for GitHub API integration. This server provides comprehensive tools for interacting with GitHub repositories, issues, pull requests, branches, and code search through a unified interface.
      15
      8 npm
      MIT