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

1. Install the GitHub CLI (gh) if not already installed:

   • macOS: brew install gh
   • Linux: sudo apt install gh
   • Windows: winget install GitHub.cli

2. 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 information
• gh_graphql_user_profile(username): Get detailed user profile data
• gh_graphql_pull_requests(owner_repo, limit, state): Get pull requests with reviewers and status
• gh_graphql_issues(owner_repo, limit, state, labels): Get issues with comments and labels
• gh_graphql_repo_contributors(owner_repo, limit): Get repository contributors and their commits
• gh_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 repositories
• gh_rest_repo_contents(owner_repo, path, ref): Get repository contents
• gh_rest_create_issue(owner_repo, title, body, labels): Create an issue
• gh_rest_create_pr(owner_repo, title, body, head, base, draft): Create a pull request
• gh_rest_branches(owner_repo): List repository branches
• gh_rest_commits(owner_repo, branch, limit): List repository commits
• gh_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

1. Update version in pyproject.toml:

[project]
version = "x.y.z"  # Update this

2. 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

3. Publish to PyPI:

# Install twine if needed
uv pip install twine

# Upload to PyPI
python -m twine upload dist/*

License

MIT