Pygithub MCP Server

🚀 PyGithub Usage Guide

This guide provides a comprehensive overview of using PyGithub, including installation, configuration, development, and troubleshooting.

📦 Installation

To install PyGithub, use the following commands:

uv add pygithub-mcp-server
uv install

Dependencies

• Python 3.10+
• MCP Python SDK
• Pydantic
• PyGithub
• UV Package Manager

💻 Usage

Initialization and Execution

To use PyGithub, follow these steps:

1. Activate the virtual environment:

   source .venv/bin/activate
   

2. Run the server:

   uv run pygithub-mcp-server
   

Configuration

Tool Group Configuration

By default, only the issues tool group is enabled. You can configure tool groups in two ways:

1. Configuration File: Create and specify a configuration file:

   export PYGITHUB_MCP_CONFIG=/path/to/pygithub_mcp_config.json
   

   Example content:

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

2. Environment Variables: Set tool group states directly:

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

Configuration File Path

The default configuration file is located at pygithub_mcp_server/settings.py. For customization, refer to README.config.md for more options.

🛠️ Development

Testing

The project includes a comprehensive test suite:

# Run all tests
pytest

# Generate a coverage report
pytest --cov

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

# Run tests based on a pattern
pytest -k "test_create_issue"

Note: Many tests are currently failing, and we are actively working on fixing them.

Development Testing with MCP Inspector

During development, you can use the MCP Inspector to test tools:

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

Through the MCP Inspector's Web UI, you can:

• Test available tools
• Interact with real GitHub repositories
• Validate success and error cases
• Document payloads

Project Structure

tests/
├── unit/                # Quick tests, no external dependencies
│   ├── config/          # Configuration tests
│   ├── tools/           # Tool registration tests
│   └── ...              # Other unit tests
└── integration/         # Tests using the real GitHub API
    ├── issues/          # Issue tool tests
    └── ...              # Other integration tests

src/
└── pygithub_mcp_server/
    ├── __init__.py
    ├── __main__.py
    ├── server.py        # Factory pattern (create_server)
    ├── version.py
    ├── config/          # Configuration system
    │   ├── __init__.py
    │   └── settings.py  # Configuration management
    ├── tools/           # Modular tool system
    │   ├── __init__.py  # Tool registration framework
    │   └── issues/      # Issue tool
    │       ├── __init__.py
    │       └── tools.py # Issue tool implementation
    ├── client/          # GitHub client
    │   ├── __init__.py
    │   └── client.py    # Main client logic
    ├── core/            # Core functionality module
    │   ├── __init__.py
    │   └── logic.py     # Core business logic
    └── utils/          # Tools and helper functions
       ├── __init__.py
       └── helper.py      # Helper function collection

🚑 Troubleshooting and Support

Common Issues

• Dependency Not Found: Run uv install to install all necessary packages.
• Configuration File Error: Check if the PYGITHUB_MCP_CONFIG environment variable is set correctly or ensure the default configuration file exists.

For further assistance, contact the support team or refer to the project documentation.