https://github.com/michaelneale/mcp-github-cli
a MCP server for github using the GH cli under the covers
https://github.com/michaelneale/mcp-github-cli
Last synced: 3 months ago
JSON representation
a MCP server for github using the GH cli under the covers
- Host: GitHub
- URL: https://github.com/michaelneale/mcp-github-cli
- Owner: michaelneale
- Created: 2025-04-30T06:59:17.000Z (6 months ago)
- Default Branch: main
- Last Pushed: 2025-05-01T08:21:29.000Z (6 months ago)
- Last Synced: 2025-07-20T09:40:38.573Z (4 months ago)
- Language: Python
- Size: 21.5 KB
- Stars: 2
- Watchers: 1
- Forks: 1
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mcp-servers - **mcp-github-cli** - a MCP server for github using the GH cli under the covers `python` `mcp` `server` `pip install git+https://github.com/michaelneale/mcp-github-cli` (🤖 AI/ML)
- awesome-mcp-servers - **mcp-github-cli** - a MCP server for github using the GH cli under the covers `python` `mcp` `server` `pip install git+https://github.com/michaelneale/mcp-github-cli` (AI/ML)
README
# 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
```sh
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:
```sh
gh auth login
```
## Test
```sh
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)
```sh
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
```python
# Get authenticated user information
gh_get_me()
```
### GraphQL Examples
```python
# 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
```python
# 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`:
```toml
[project]
version = "x.y.z" # Update this
```
2. Build the package:
```bash
# 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:
```bash
# Install twine if needed
uv pip install twine
# Upload to PyPI
python -m twine upload dist/*
```
## License
MIT