michaelneale/mcp-github-cli
If you are the rightful owner of mcp-github-cli and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.
MCP server that provides focused GraphQL and REST API tools for interacting with GitHub.
mcp-github-cli
MCP server that provides focused GraphQL and REST API tools for interacting with GitHub. This server offers a streamlined set of powerful tools that leverage GitHub's APIs to provide rich data and functionality.
Usage
uvx mcp-github-cli
Will run from PyPI. This can be used in goose or claude.
Prerequisites
-
Install the GitHub CLI (
gh) if not already installed:- macOS:
brew install gh - Linux:
sudo apt install gh - Windows:
winget install GitHub.cli
- macOS:
-
Authenticate with GitHub:
gh auth login
Test
uv run python main.py --test
This will run a comprehensive test suite that verifies:
- Authentication status with GitHub
- User information retrieval (gh_get_me)
- GraphQL query functionality (viewer info)
- REST API repository search
- GraphQL repository information retrieval
- REST API branch listing
The test output provides a good demonstration of the capabilities of the different tools.
Usage from source
Running from CLI (Goose, or to try it)
uv --directory /path/to/mcp-github-cli run python main.py
Features
This MCP server focuses on providing powerful, focused tools that leverage GitHub's GraphQL and REST APIs:
User Information
gh_get_me(): Get detailed information about the authenticated user
GraphQL Tools
GraphQL tools provide rich, nested data in a single request:
gh_graphql_repo_info(owner_repo): Get comprehensive repository informationgh_graphql_user_profile(username): Get detailed user profile datagh_graphql_pull_requests(owner_repo, limit, state): Get pull requests with reviewers and statusgh_graphql_issues(owner_repo, limit, state, labels): Get issues with comments and labelsgh_graphql_repo_contributors(owner_repo, limit): Get repository contributors and their commitsgh_custom_graphql(query, variables): Execute a custom GraphQL query
REST API Tools
REST tools provide specific functionality for common operations:
gh_rest_search_repos(query, limit): Search for repositoriesgh_rest_repo_contents(owner_repo, path, ref): Get repository contentsgh_rest_create_issue(owner_repo, title, body, labels): Create an issuegh_rest_create_pr(owner_repo, title, body, head, base, draft): Create a pull requestgh_rest_branches(owner_repo): List repository branchesgh_rest_commits(owner_repo, branch, limit): List repository commitsgh_rest_api(endpoint, method, data, query_params): Execute a custom REST API request
Examples
Here are examples of using these tools:
User Information
# Get authenticated user information
gh_get_me()
GraphQL Examples
# Get repository information
gh_graphql_repo_info("block/goose")
# Get user profile
gh_graphql_user_profile("octocat")
# Get open pull requests
gh_graphql_pull_requests("block/goose", 5, "OPEN")
# Get issues with specific labels
gh_graphql_issues("block/goose", 10, "OPEN", ["bug", "help wanted"])
# Custom GraphQL query
gh_custom_graphql("""
query {
viewer {
login
name
}
}
""")
REST API Examples
# Search for repositories
gh_rest_search_repos("language:python stars:>1000", 5)
# Get file contents
gh_rest_repo_contents("block/goose", "README.md")
# Create an issue
gh_rest_create_issue("your-username/your-repo", "Bug report", "There's a bug", ["bug"])
# List branches
gh_rest_branches("block/goose")
# Custom REST API request
gh_rest_api("repos/block/goose", "GET", query_params={"sort": "updated"})
Building and Publishing
- Update version in
pyproject.toml:
[project]
version = "x.y.z" # Update this
- Build the package:
# Clean previous builds
rm -rf dist/*
# Or build in a clean environment using uv
uv venv .venv
source .venv/bin/activate
uv pip install build
python -m build
- Publish to PyPI:
# Install twine if needed
uv pip install twine
# Upload to PyPI
python -m twine upload dist/*
License
MIT
