github-mcp
Provides tools for interacting with GitHub, including listing and creating issues, managing pull requests, searching code, and reading file contents.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@github-mcp Get issue #1234 in cli/cli"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
github-mcp
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 โ
GitHubErrorcarries HTTP status, parsed message, and endpoint.โ Input validation โ catches bad inputs before the network round-trip.
๐ Text files decoded โ
get_file_contentreturns UTF-8 text underdecoded_contentfor 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 (filter by state, labels, since) โ PRs filtered out |
| Get a single issue by number |
| Create an issue (with optional labels) |
| List PRs (filter by state) |
| Get a single PR by number |
| Search code across GitHub (requires code-search scope) |
| Read a file at a ref; text files returned UTF-8-decoded |
Full parameter docs: docs/USAGE.md.
Install
pip install github-mcpOr with uv:
uv tool install github-mcpRequires Python 3.10+.
Authenticate
Create a GitHub personal access token:
Fine-grained (recommended): https://github.com/settings/personal-access-tokens/new
Classic (legacy): https://github.com/settings/tokens/new
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-mcpCursor
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/clilabeledbug."
"Get issue #1234 in
cli/cliand summarize the discussion."
"Create a new issue in
my-org/my-repotitledBug: login fails on Safariwith bodySteps to reproduce: ...."
"Show me the contents of
src/main.pyincli/clion themainbranch."
"Search GitHub for
function authenticateincli/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 integrationQuality gates (run on every PR):
ruff check src tests
ruff format --check src tests
mypy srcLicense
MIT โ see LICENSE.
Available Tools
7 toolscreate_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
Scored across 7 tools
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.
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.
With 7 tools, the server is well-scoped for basic GitHub interactions. The number is neither too sparse nor excessive for its purpose.
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
Related MCP Connectors
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yoโฆ
An MCP server that gives your AI access to the source code and docs of all public github repos
GitHub Copilot MCP: code, repo, PR, workflow tools for AI assistants.
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
Related MCP Servers
- AlicenseBqualityDmaintenanceAn 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.4ISC
- AlicenseBqualityCmaintenanceMCP server that exposes GitHub operations as tools for AI agents, enabling code search, issue management, and PR review.12MIT
- FlicenseNot gradedqualityDmaintenanceA 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-
- AlicenseBqualityDmaintenanceMCP (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.158 npmMIT