GitHub MCP Server

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

Related MCP server: github-mcp

Installation

1. Clone the repository:

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

2. Install the package:

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

     # 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:

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

Usage

1. Start the server:

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:

     {
       "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:

pip install -e ".[dev]"

2. Run tests:

pytest

3. Run linting:

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

• Cursor IDE

• Cursor MCP Server

• GitHub API

• GitHubauthlib