MCP Servers

PyGithub MCP Server

Enables AI assistants to interact with GitHub through the PyGithub library, providing tools for managing issues, repositories, pull requests, and other GitHub operations with intelligent parameter handling and error management.

AstroMined

Version Control

Visit Server

Tools

create_issue

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

list_issues

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

get_issue

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

update_issue

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

add_issue_comment

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

list_issue_comments

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

update_issue_comment

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

push_files

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

delete_issue_comment

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

add_issue_labels

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

remove_issue_label

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

get_repository

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

create_repository

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

fork_repository

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

search_repositories

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

get_file_contents

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

create_or_update_file

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

create_branch

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

list_commits

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

README

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

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

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

Comment Operations

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

Label Operations

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

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

Create and activate a virtual environment:

uv venv
source .venv/bin/activate

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

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
Build errors:
- Use --no-build-isolation flag with uv build
- Ensure Python 3.10+ is being used
- Verify all dependencies are installed
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

Recommended Servers

MCP Package Docs Server

Facilitates LLMs to efficiently access and fetch structured documentation for packages in Go, Python, and NPM, enhancing software development with multi-language support and performance optimization.

Featured

Local

TypeScript

Gitingest-MCP

An MCP server for gitingest. It allows MCP clients like Claude Desktop, Cursor, Cline etc to quickly extract information about Github repositories including repository summaries, project directory structure, file contents, etc

Featured

Local

Python

Linear MCP Server

Enables interaction with Linear's API for managing issues, teams, and projects programmatically through the Model Context Protocol.

Featured

JavaScript

Linear MCP Server

A Model Context Protocol server that integrates with Linear's issue tracking system, allowing LLMs to create, update, search, and comment on Linear issues through natural language interactions.

Featured

JavaScript

JSON Resume MCP Server

A server that enhances AI assistants with the ability to update your JSON Resume by analyzing your coding projects, automatically extracting skills and generating professional descriptions.

Official

Local

TypeScript

Edit File Lines MCP Server

A TypeScript-based MCP server that provides tools for making precise line-based edits to text files within allowed directories.

Local

TypeScript

MCP Source Relation Server

Analyzes source code dependencies across multiple programming languages in the specified directory to identify file relationships, assisting in dependency management and project structure understanding.

Local

Python

Git File Forensics MCP

Provides deep git file-level forensics tools to analyze detailed file histories, changes, and patterns within git repositories, focusing on individual file analysis rather than repository-wide operations.

Local

JavaScript

MCP Git Repo Browser

A Node.js server that allows browsing Git repositories through MCP, providing tools to view directory structures and read important files from repositories.

Local

JavaScript

MCP Code Indexer

A smart code retrieval tool based on Model Context Protocol that provides efficient and accurate code repository search capabilities for large language models.

Local

Python