PyGithub MCP server

The PyGithub MCP Server provides a Model Context Protocol server that allows AI assistants to interact with the GitHub API through PyGithub. It enables operations like managing issues, repositories, and pull requests via a structured tool interface.

Installation

Prerequisites

• Python 3.10 or higher
• UV package manager (recommended)

Setup Steps

1. Create and activate a virtual environment:

uv venv
source .venv/bin/activate

2. Install the server and its dependencies:

uv pip install -e .

Configuration

Basic Server Configuration

Add the PyGithub MCP Server to your MCP settings file (such as claude_desktop_config.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "github": {
      "command": "/path/to/repo/.venv/bin/python",
      "args": ["-m", "pygithub_mcp_server"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
      }
    }
  }
}

Tool Group Configuration Options

You can selectively enable or disable tool groups using either of these methods:

Using a Configuration File

1. Create a JSON configuration file (e.g., pygithub_mcp_config.json):

{
  "tool_groups": {
    "issues": {"enabled": true},
    "repositories": {"enabled": true},
    "pull_requests": {"enabled": false},
    "discussions": {"enabled": false},
    "search": {"enabled": true}
  }
}

2. Set the path to this configuration file:

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

Using Environment Variables

Alternatively, configure tool groups directly with environment variables:

export PYGITHUB_ENABLE_ISSUES=true
export PYGITHUB_ENABLE_REPOSITORIES=true
export PYGITHUB_ENABLE_PULL_REQUESTS=false

Note: By default, only the issues tool group is enabled.

Usage Examples

Managing Issues

Creating an Issue

{
  "owner": "username",
  "repo": "repository",
  "title": "Issue Title",
  "body": "Issue description",
  "assignees": ["username1", "username2"],
  "labels": ["bug", "help wanted"],
  "milestone": 1
}

Getting Issue Details

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1
}

Updating an Issue

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "title": "Updated Title",
  "body": "Updated description",
  "state": "closed",
  "labels": ["bug", "wontfix"]
}

Working with Comments

Adding a Comment

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "body": "This is a comment"
}

Listing Comments

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "per_page": 10
}

Updating a Comment

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "comment_id": 123456789,
  "body": "Updated comment text"
}

Managing Labels

Adding Labels

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "labels": ["enhancement", "help wanted"]
}

Removing a Label

{
  "owner": "username",
  "repo": "repository",
  "issue_number": 1,
  "label": "enhancement"
}

Troubleshooting

If you encounter problems with the server:

• Server fails to start:

  • Verify the Python path in your MCP settings points to the correct virtual environment
  • Ensure all requirements are properly installed
  • Check that your GitHub token is set and valid

• GitHub API errors:

  • Verify your token has the necessary permissions
  • Check the pygithub_mcp_server.log file for detailed error traces
  • Ensure you haven't exceeded GitHub API rate limits

• Parameter handling:

  • The server intelligently handles optional parameters
  • Only includes provided parameters in API calls
  • Converts primitive types to GitHub objects (e.g., milestone numbers)
  • Provides clear error messages for invalid inputs

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "github" '{"command":"/path/to/repo/.venv/bin/python","args":["-m","pygithub_mcp_server"],"env":{"GITHUB_PERSONAL_ACCESS_TOKEN":"your-token-here"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "github": {
            "command": "/path/to/repo/.venv/bin/python",
            "args": [
                "-m",
                "pygithub_mcp_server"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "github": {
            "command": "/path/to/repo/.venv/bin/python",
            "args": [
                "-m",
                "pygithub_mcp_server"
            ],
            "env": {
                "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token-here"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect