# 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