Skip to main content
Glama
Sign In
enesjakozh
PyGithub MCP Server

PyGithub MCP Server

by AstroMined
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

PyGithub MCP Server

A Model Context Protocol server that provides tools for interacting with the GitHub API through PyGithub. This server enables AI assistants to perform GitHub operations like managing issues, repositories, and pull requests.

Features

  • Modular Tool Architecture:

    • Configurable tool groups that can be enabled/disabled

    • Domain-specific organization (issues, repositories, etc.)

    • Flexible configuration via file or environment variables

    • Clear separation of concerns with modular design

    • Easy extension with consistent patterns

  • Complete GitHub Issue Management:

    • Create and update issues

    • Get issue details and list repository issues

    • Add, list, update, and delete comments

    • Manage issue labels

    • Handle assignees and milestones

  • Smart Parameter Handling:

    • Dynamic kwargs building for optional parameters

    • Proper type conversion for GitHub objects

    • Validation for all input parameters

    • Clear error messages for invalid inputs

  • Robust Implementation:

    • Object-oriented GitHub API interactions via PyGithub

    • Centralized GitHub client management

    • Proper error handling and rate limiting

    • Clean API abstraction through MCP tools

    • Comprehensive pagination support

    • Detailed logging for debugging

Related MCP server: GitHub MCP Server

Documentation

Comprehensive guides are available in the docs/guides directory:

  • error-handling.md: Error types, handling patterns, and best practices

  • security.md: Authentication, access control, and content security

  • tool-reference.md: Detailed tool documentation with examples

See these guides for detailed information about using the PyGithub MCP Server.

Usage Examples

Issue Operations

  1. Creating an Issue

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

  1. Getting Issue Details

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

  1. Updating an Issue

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

Comment Operations

  1. Adding a Comment

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

  1. Listing Comments

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

  1. Updating a Comment

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

Label Operations

  1. Adding Labels

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

  1. Removing a Label

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

All operations handle optional parameters intelligently:

  • Only includes provided parameters in API calls

  • Converts primitive types to GitHub objects (e.g., milestone number to Milestone object)

  • Provides clear error messages for invalid parameters

  • Handles pagination automatically where applicable

Installation

  1. Create and activate a virtual environment:

uv venv
source .venv/bin/activate

  1. Install dependencies:

uv pip install -e .

Configuration

Basic Configuration

Add the server to your MCP settings (e.g., 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

The server supports selectively enabling or disabling tool groups through configuration. You can configure this in two ways:

1. Configuration File

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}
  }
}

Then specify this file in your environment:

export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json

2. Environment Variables

Alternatively, use environment variables to configure tool groups:

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

By default, only the issues tool group is enabled. See README.config.md for more detailed configuration options.

Development

Testing

The project includes a comprehensive test suite:

# Run all tests
pytest

# Run tests with coverage report
pytest --cov

# Run specific test file
pytest tests/test_operations/test_issues.py

# Run tests matching a pattern
pytest -k "test_create_issue"

Note: Many tests are currently failing and under investigation. This is a known issue being actively worked on.

Testing with MCP Inspector

Test MCP tools during development using the MCP Inspector:

source .venv/bin/activate  # Ensure venv is activated
npx @modelcontextprotocol/inspector -e GITHUB_PERSONAL_ACCESS_TOKEN=your-token-here uv run pygithub-mcp-server

Use the MCP Inspector's Web UI to:

  • Experiment with available tools

  • Test with real GitHub repositories

  • Verify success and error cases

  • Document working payloads

Project Structure

tests/
├── unit/                # Fast tests without external dependencies
│   ├── config/          # Configuration tests
│   ├── tools/           # Tool registration tests
│   └── ...              # Other unit tests
└── integration/         # Tests with real GitHub API
    ├── issues/          # Issue tools tests
    └── ...              # Other integration tests
src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # Server factory (create_server)
    ├── version.py
    ├── config/          # Configuration system
    │   ├── __init__.py
    │   └── settings.py  # Configuration management
    ├── tools/           # Modular tool system
    │   ├── __init__.py  # Tool registration framework
    │   └── issues/      # Issue tools
    │       ├── __init__.py
    │       └── tools.py # Issue tool implementations
    ├── client/          # GitHub client functionality
    │   ├── __init__.py
    │   ├── client.py    # Core GitHub client
    │   └── rate_limit.py # Rate limit handling
    ├── converters/      # Data transformation
    │   ├── __init__.py
    │   ├── parameters.py # Parameter formatting
    │   ├── responses.py # Response formatting
    │   ├── common/      # Common converters
    │   ├── issues/      # Issue-related converters
    │   ├── repositories/ # Repository converters
    │   └── users/       # User-related converters
    ├── errors/          # Error handling
    │   ├── __init__.py
    │   └── exceptions.py # Custom exceptions
    ├── operations/      # GitHub operations
    │   ├── __init__.py
    │   └── issues.py
    ├── schemas/         # Data models
    │   ├── __init__.py
    │   ├── base.py
    │   ├── issues.py
    │   └── ...
    └── utils/           # General utilities
        ├── __init__.py
        └── environment.py # Environment utilities

Troubleshooting

  1. Server fails to start:

    • Verify venv Python path in MCP settings

    • Ensure all requirements are installed in venv

    • Check GITHUB_PERSONAL_ACCESS_TOKEN is set and valid

  2. Build errors:

    • Use --no-build-isolation flag with uv build

    • Ensure Python 3.10+ is being used

    • Verify all dependencies are installed

  3. GitHub API errors:

    • Check token permissions and validity

    • Review pygithub_mcp_server.log for detailed error traces

    • Verify rate limits haven't been exceeded

Dependencies

  • Python 3.10+

  • MCP Python SDK

  • Pydantic

  • PyGithub

  • UV package manager

License

MIT

Available Tools

19 tools
add_issue_commentC

Add a comment to an issue.

Args:
    params: Parameters for adding a comment including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number to comment on
        - body: Comment text

Returns:
    Created comment details from GitHub API

Inputs: params (required).

add_issue_labelsC

Add labels to an issue.

Args:
    params: Parameters for adding labels including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number
        - labels: Labels to add

Returns:
    Updated list of labels from GitHub API

Inputs: params (required).

create_branchC

Create a new branch in a GitHub repository.

Args:
    params: Dictionary with branch parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - branch: Name for new branch
        - from_branch: Source branch (optional, defaults to repo default)

Returns:
    MCP response with branch creation result

Inputs: params (required).

create_issueA

Create a new issue in a GitHub repository.

Args:
    params_dict: Parameters for creating an issue including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - title: Issue title
        - body: Issue description (optional)
        - assignees: List of usernames to assign
        - labels: List of labels to add
        - milestone: Milestone number (optional)

Returns:
    Created issue details from GitHub API

Inputs: params_dict (required).

create_or_update_fileA

Create or update a file in a GitHub repository.

Args:
    params: Dictionary with file parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - path: Path where to create/update the file
        - content: Content of the file
        - message: Commit message
        - branch: Branch to create/update the file in
        - sha: SHA of file being replaced (for updates, optional)

Returns:
    MCP response with file creation/update result

Inputs: params (required).

create_repositoryB

Create a new GitHub repository.

Args:
    params: Dictionary with repository creation parameters
        - name: Repository name
        - description: Repository description (optional)
        - private: Whether the repository should be private (optional)
        - auto_init: Initialize repository with README (optional)

Returns:
    MCP response with created repository details

Inputs: params (required).

delete_issue_commentC

Delete an issue comment.

Args:
    params: Parameters for deleting a comment including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number containing the comment
        - comment_id: Comment ID to delete

Returns:
    Empty response on success

Inputs: params (required).

fork_repositoryC

Fork an existing GitHub repository.

Args:
    params: Dictionary with fork parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - organization: Organization to fork to (optional)

Returns:
    MCP response with forked repository details

Inputs: params (required).

get_file_contentsB

Get contents of a file in a GitHub repository.

Args:
    params: Dictionary with file parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - path: Path to file/directory
        - branch: Branch to get contents from (optional)

Returns:
    MCP response with file content data

Inputs: params (required).

get_issueC

Get details about a specific issue.

Args:
    params: Parameters for getting an issue including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number to retrieve

Returns:
    Issue details from GitHub API

Inputs: params (required).

get_repositoryB

Get details about a GitHub repository.

Args:
    params: Dictionary with repository parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name

Returns:
    MCP response with repository details

Inputs: params (required).

list_commitsC

List commits in a GitHub repository.

Args:
    params: Dictionary with commit parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - page: Page number (optional)
        - per_page: Results per page (optional)
        - sha: Branch name or commit SHA (optional)

Returns:
    MCP response with list of commits

Inputs: params (required).

list_issue_commentsB

List comments on an issue.

Args:
    params: Parameters for listing comments including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number
        - since: Filter by date (optional)
        - page: Page number (optional)
        - per_page: Results per page (optional)

Returns:
    List of comments from GitHub API

Inputs: params (required).

list_issuesA

List issues from a GitHub repository.

Args:
    params: Parameters for listing issues including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - state: Issue state (open, closed, all)
        - labels: Filter by labels
        - sort: Sort field (created, updated, comments)
        - direction: Sort direction (asc, desc)
        - since: Filter by date
        - page: Page number for pagination
        - per_page: Number of results per page (max 100)

Returns:
    List of issues from GitHub API

Inputs: params (required).

push_filesA

Push multiple files to a GitHub repository in a single commit.

Args:
    params: Dictionary with file parameters
        - owner: Repository owner (username or organization)
        - repo: Repository name
        - branch: Branch to push to
        - files: List of files to push, each with path and content
        - message: Commit message

Returns:
    MCP response with file push result

Inputs: params (required).

remove_issue_labelB

Remove a label from an issue.

Args:
    params: Parameters for removing a label including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number
        - label: Label to remove

Returns:
    Empty response on success or error if label doesn't exist

Inputs: params (required).

search_repositoriesC

Search for GitHub repositories.

Args:
    params: Dictionary with search parameters
        - query: Search query
        - page: Page number for pagination (optional)
        - per_page: Results per page (optional)

Returns:
    MCP response with matching repositories

Inputs: params (required).

update_issueB

Update an existing issue.

Args:
    params: Parameters for updating an issue including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number to update
        - title: New title (optional)
        - body: New description (optional)
        - state: New state (optional)
        - labels: New labels (optional)
        - assignees: New assignees (optional)
        - milestone: New milestone number (optional)

Returns:
    Updated issue details from GitHub API

Inputs: params (required).

update_issue_commentB

Update an issue comment.

Args:
    params: Parameters for updating a comment including:
        - owner: Repository owner (user or organization)
        - repo: Repository name
        - issue_number: Issue number containing the comment
        - comment_id: Comment ID to update
        - body: New comment text

Returns:
    Updated comment details from GitHub API

Inputs: params (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.5/5.0

    Scored across 19 tools

    Disambiguation4/5

    Most tools have distinct purposes targeting specific GitHub resources and actions, like issues, files, repositories, and branches. However, there is some overlap between 'create_or_update_file' and 'push_files' as both handle file modifications, which could cause confusion. All other tools are clearly separated by their target resources.

    Naming Consistency5/5

    All tool names follow a consistent snake_case pattern with clear verb_noun structures, such as 'create_issue', 'list_commits', and 'update_issue_comment'. The naming is uniform across all 19 tools, making them predictable and easy to understand for an agent.

    Tool Count4/5

    With 19 tools, the count is slightly high but reasonable for a comprehensive GitHub API server covering issues, repositories, files, and branches. It provides extensive functionality without being overwhelming, though it borders on being heavy compared to typical well-scoped servers.

    Completeness5/5

    The tool set offers complete CRUD and lifecycle coverage for key GitHub domains, including issues (create, get, update, delete, comment, label), repositories (create, get, fork, search), files (create/update, get, push), and branches (create). There are no obvious gaps, enabling agents to handle common workflows effectively.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • GitHub MCP Server

      asbloom-py
      A
      license
      Not graded
      quality
      D
      maintenance
      Enables interaction with GitHub through the GitHub API, supporting file operations, repository management, advanced search, and issue tracking with comprehensive error handling and automatic branch creation.
      443 npm
      1
      ISC

    • GitHub MCP Server

      pipseedai
      A
      license
      A
      quality
      Not graded
      maintenance
      Enables AI agents to interact with GitHub repositories through the GitHub REST API for managing files, issues, and repository metadata. It supports both read operations like searching code and write operations such as creating repositories and updating issue comments.
      9
      -

    Appeared in Searches