github-mcp

An MCP (Model COntext Protocol) server that gives AI assistants direct access to GitHub. Exposing ~22 GitHub REST tools covering repos, files, issues, pull requests, as well as searching.

Table of Contents

1. Features
2. Installation
3. Usage
4. Contributing

Features

A single stdio MCP server (built on FastMCP) exposing 23 GitHub REST tools grouped into four areas:

• Repositories & files — github_list_repos, github_get_repo, github_list_branches, github_list_commits, github_get_file_contents, github_list_directory, github_create_or_update_file, github_create_branch
• Issues — github_list_issues, github_get_issue, github_create_issue, github_update_issue, github_add_issue_comment
• Pull requests — github_list_pull_requests, github_get_pull_request, github_create_pull_request, github_merge_pull_request, github_add_pr_comment
• Search — github_search_repositories, github_search_code, github_search_issues, github_search_users, github_search_commits

Under the hood:

• Async HTTP via a shared, lazily-initialised httpx.AsyncClient against the pinned GitHub API version (2022-11-28).
• Automatic pagination — list endpoints follow the Link: rel="next" header up to a configurable item cap.
• Typed inputs — every tool validates its arguments with Pydantic models.
• Actionable errors — common GitHub failures (401, 403/rate-limit with reset time, 404, 409, 422, timeouts) are translated into clear, human-readable messages.
• Flexible auth — reads a fine-grained PAT from GITHUB_TOKEN, falling back to GITHUB_PAT.

Installation

Prerequisites

• Python 3.12 or later
• Dependencies mcp[cli]>=1.0.0, httpx>=0.27.0, pydantic>=2.0.0 (see pyproject.toml) (project uses poetry for dependency management)

Install from PyPi

pip install github-mcp

# or using poetry
poetry add github-mcp

Build from source

git clone https://github.com/LWaetzig/github-mcp.git
cd github-mcp
pip install -e .

Usage

• Detailed documentation about single tools can be found this sphinx documentation

Prerequisites

Create a fine-grained Personal Access Token (PAT)

1. Go to GitHub -> Settings -> Developer settings -> Personal access tokens -> Fine-grained tokens (direct link: https://github.com/settings/tokens?type=beta)
2. Generate new token
3. Set Resource owner and Repository access as appropriate
4. Grant these Repository permissions (minimum for full read + write):

Read-only subset: grant only Read-only access to Contents, Issues, Pull requests, and Metadata if you don't need write tools.

export GITHUB_TOKEN=github_pat_...

Or copy .env.example -> .env and fill in the token (load with source .env).

Integrating with Claude Desktop

Add the server to your Claude Desktop configuration:

Add the github entry under mcpServers, replacing the path with the absolute path to your clone:

{
  "mcpServers" : {
    "github" : {
      "command" : "python",
      "args" : ["-m", "github-mcp"],
      "env" : {
        "GITHUB_TOKEN" : "github_pat_..."
      }
    }
  }
}

Restart Claude Desktop. You should see the github tools available int he tool picker.

Integration with Other MCP Clients

Any MCP client (e.g. Cline, GitHub Copilot, or custm tools) can use this server. Configuration depends on your assistant, in most cases there is a config to change.

Contribution

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-feature)
3. Commit your changes with clear messages
4. Push to your fork
5. Open a pull request

Live testing with MCP Inspector (requires a real token)

GITHUB_TOKEN=... 
npx @modelcontextprotocol/inspector 
uv run github-mcp

Then call github_search_repositories (q="mcp language:python") or github_get_repo (owner="modelcontextprotocol", repo="python-sdk") to verify auth, pagination, and formatting end-to-end.

Upcoming Features

• Projects v2: Requires GitHub's GraphQL API (/graphql). Add a graphql_client.py alongside client.py and a new tools/projects.py module.
• Actions: Also REST-based but with many endpoints. Add tools/actions.py importing from client.py.