# GitHub MCP Server

![GitHub MCP Server](img/GitHub_MCP_Server.png)

A Model Context Protocol (MCP) server that provides GitHub integration tools for AI assistants. This server implements a set of tools that allow AI models to interact with GitHub repositories, issues, pull requests, and content.

## Features

- Repository Management
  - List repositories
  - Get repository details
- Issue Management
  - List issues
  - Create issues
- Pull Request Management
  - List pull requests
  - Create pull requests
- Content Management
  - Get file content
  - List directory contents

## Installation

1. Clone the repository:

```bash
git clone https://github.com/yourusername/github-mcp.git
cd github-mcp
```

2. Install the package:

```bash
pip install -e .
```

## Authentication

This server uses `githubauthlib` for secure GitHub authentication. The library retrieves GitHub tokens from your system's keychain:

- macOS: Uses Keychain Access
- Windows: Uses Credential Manager
- Linux: Uses libsecret

To set up authentication:

1. Install the required system dependencies:

   - macOS: No additional setup required
   - Windows: No additional setup required
   - Linux: Install libsecret

     ```bash
     # Ubuntu/Debian
     sudo apt-get install libsecret-tools

     # Fedora
     sudo dnf install libsecret
     ```

2. Configure your GitHub credentials:
   - The server will automatically use your Git credentials from the system keychain
   - If no credentials are found, you'll need to configure Git with your GitHub credentials:

     ```bash
     git config --global credential.helper store
     # Then perform a Git operation that requires authentication
     ```

## Usage

1. Start the server:

```bash
python -m github_mcp.server
```

The server will start on `http://localhost:8000` by default.

2. Configure Cursor IDE:
   - Open Cursor IDE settings
   - Add the following MCP server configuration:

     ```json
     {
       "mcp": {
         "servers": [
           {
             "name": "github-mcp",
             "url": "http://localhost:8000/sse"
           }
         ]
       }
     }
     ```

## API Endpoints

- `GET /`: Server information and available tools
- `POST /tool`: Synchronous tool calls
- `GET /sse`: Server-Sent Events endpoint for streaming responses

## Available Tools

### Repository Tools

- `list_repositories`: List GitHub repositories
  - Parameters:
    - `visibility` (optional): "all", "public", or "private"
    - `sort` (optional): "created", "updated", "pushed", or "full_name"
- `get_repository`: Get repository details
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name

### Issue Tools

- `list_issues`: List repository issues
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `state` (optional): "open", "closed", or "all"
    - `labels` (optional): List of label names
- `create_issue`: Create a new issue
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `title`: Issue title
    - `body` (optional): Issue description
    - `labels` (optional): List of label names
    - `assignees` (optional): List of assignee usernames

### Pull Request Tools

- `list_pull_requests`: List repository pull requests
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `state` (optional): "open", "closed", or "all"
    - `sort` (optional): "created", "updated", "popularity", or "long-running"
- `create_pull_request`: Create a new pull request
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `title`: Pull request title
    - `body` (optional): Pull request description
    - `head`: Source branch
    - `base` (optional): Target branch (default: "main")
    - `draft` (optional): Create as draft (default: false)

### Content Tools

- `get_file_content`: Get file content
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `path`: File path
    - `ref` (optional): Branch/tag/commit reference
- `list_directory`: List directory contents
  - Parameters:
    - `owner`: Repository owner
    - `repo`: Repository name
    - `path` (optional): Directory path (default: "")
    - `ref` (optional): Branch/tag/commit reference

## Development

1. Install development dependencies:

```bash
pip install -e ".[dev]"
```

2. Run tests:

```bash
pytest
```

3. Run linting:

```bash
ruff check .
```

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io)
- [Cursor IDE](https://cursor.com)
- [Cursor MCP Server](https://docs.cursor.com/context/model-context-protocol)
- [GitHub API](https://docs.github.com/en/rest)
- [GitHubauthlib](https://pypi.org/project/githubauthlib/)