# GitHub CLI MCP Server
An MCP (Model Context Protocol) server that wraps the GitHub CLI (`gh`) tool, providing comprehensive access to GitHub functionality through a standardized interface.
## Features
This server exposes the following GitHub CLI functionality:
### Repository Management
- `gh_repo_list` - List repositories for a user or organization
- `gh_repo_view` - View information about a repository
- `gh_repo_create` - Create a new repository
### Pull Requests
- `gh_pr_list` - List pull requests in a repository
- `gh_pr_view` - View a pull request
- `gh_pr_create` - Create a pull request
- `gh_pr_merge` - Merge a pull request
- `gh_pr_checkout` - Check out a pull request locally
### Issues
- `gh_issue_list` - List issues in a repository
- `gh_issue_view` - View an issue
- `gh_issue_create` - Create an issue
- `gh_issue_close` - Close an issue
### GitHub Actions
- `gh_workflow_list` - List workflows in a repository
- `gh_workflow_view` - View details about a workflow
- `gh_run_list` - List recent workflow runs
- `gh_run_view` - View details about a workflow run
### Releases
- `gh_release_list` - List releases in a repository
- `gh_release_view` - View information about a release
- `gh_release_create` - Create a new release
### Search
- `gh_search_repos` - Search for repositories
- `gh_search_issues` - Search for issues and pull requests
### Gists
- `gh_gist_list` - List your gists
- `gh_gist_create` - Create a new gist
### Other
- `gh_api` - Make authenticated GitHub API requests
- `gh_auth_status` - View authentication status
- `gh_status` - Print information about issues, PRs, and notifications
## Prerequisites
- Python 3.10 or higher
- GitHub CLI (`gh`) installed and authenticated
- Install: https://cli.github.com/
- Authenticate: `gh auth login`
## Installation
### From GitHub
```bash
git clone https://github.com/munch-group/gh-mcp.git
cd gh-mcp
pip install -e .
```
### Prerequisites
- Python 3.10 or higher
- GitHub CLI (`gh`) installed and authenticated
- Install: https://cli.github.com/
- Authenticate: `gh auth login`
Verify GitHub CLI is authenticated:
```bash
gh auth status
```
## Usage
### With Claude Desktop
```bash
# After installing with pip
claude mcp add gh gh-mcp-server
# Or run directly
claude mcp add gh python /path/to/gh-mcp/server.py
```
Or add manually to your Claude Desktop configuration:
```json
{
"mcpServers": {
"gh": {
"command": "python",
"args": ["/path/to/gh-mcp/server.py"]
}
}
}
```
### Standalone
Run the server directly:
```bash
python server.py
```
The server communicates via stdin/stdout using the MCP protocol.
## Examples
Once configured, you can use the tools through your MCP client. For example, with Claude Code:
- "List all open pull requests in my repository"
- "Create a new issue titled 'Bug in login page'"
- "Show me the status of workflow run #123"
- "Search for Python repositories with more than 1000 stars"
- "View release information for version v1.0.0"
## Tool Parameters
Most tools accept optional parameters for filtering and customization. See the tool descriptions in the code for full parameter details.
Common parameters include:
- `repository`: Specify repository in `OWNER/REPO` format (defaults to current repo)
- `limit`: Maximum number of items to return
- `state`: Filter by state (open, closed, all, etc.)
- `web`: Open result in web browser instead of returning data
## Error Handling
The server handles errors gracefully and returns informative error messages:
- Command timeouts (60 seconds)
- Invalid parameters
- gh CLI errors
- Authentication issues
## Security
This server executes `gh` commands with the permissions of the authenticated GitHub CLI user. Ensure you trust any client using this server, as it can perform actions on your behalf such as:
- Creating/modifying repositories
- Creating/closing issues and pull requests
- Triggering workflows
- Creating releases
## License
MIT
