GitHub MCP Server

A Model Context Protocol (MCP) server that integrates with GitHub's API to provide tools for automation and workflow orchestration. This server enables triggering repository dispatch events, creating issues, and retrieving repository information.

Features

• 🎯 Repository Dispatch: Trigger GitHub repository_dispatch events with custom event types and JSON payloads (with full 日本語 support)

• 🐛 Issue Creation: Create GitHub issues as a fallback mechanism

• 📊 Repository Information: Retrieve detailed repository metadata

• 🔐 Secure Authentication: PAT-based authentication with environment variable management

• 🧪 Comprehensive Testing: Full pytest coverage with unit tests

• 📝 Japanese Language Support: Handle Japanese characters in payloads and metadata

Related MCP server: GitHub MCP Server

Prerequisites

• Python 3.9+

• A GitHub Personal Access Token (PAT) with repo and workflow scopes

• git for version control

Installation

From Source

git clone https://github.com/ai-info-x/github-mcp-server.git
cd github-mcp-server
pip install -e .

With Development Dependencies

pip install -e ".[dev]"

Authentication Setup

Step 1: Generate GitHub Personal Access Token

1. Go to https://github.com/settings/tokens

2. Click Generate new token (classic)

3. Give it a descriptive name: github-mcp-server

4. Select required scopes:

   • ✓ repo (full control of private repositories)

   • ✓ workflow (update GitHub Action workflows)

5. Set expiration (90 days recommended)

6. Click Generate token and copy the token immediately

Step 2: Configure Environment

Option A: Using .env File (Recommended)

# Copy the template
cp .env.template .env

# Edit .env with your token
# GITHUB_TOKEN=ghp_your_token_here

Option B: Export Environment Variable

export GITHUB_TOKEN="ghp_your_token_here"

Option C: System-wide Configuration

# Permanently set in ~/.bashrc or ~/.zshrc
echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.bashrc
source ~/.bashrc

⚠️ Security Note: Never commit .env to version control. The .gitignore already excludes it.

Usage

Running the MCP Server

# With environment variable set
GITHUB_TOKEN=ghp_your_token_here python -m src.github_mcp_server

# Or with .env file
python -m src.github_mcp_server

Available Tools

1. trigger_repository_dispatch

Trigger a custom repository dispatch event.

Parameters:

• owner (string, required): Repository owner (username or organization)

• repo (string, required): Repository name

• event_type (string, required): Event type identifier (e.g., my-event, build-trigger)

• payload (object, optional): Event payload as JSON object

Example:

{
    "owner": "ai-info-x",
    "repo": "my-repo",
    "event_type": "build-release",
    "payload": {
        "version": "v1.0.0",
        "message": "Release build initiated",
        "環境": "本番"  # Japanese characters supported
    }
}

Response:

{
    "success": true,
    "message": "Repository dispatch 'build-release' triggered successfully",
    "owner": "ai-info-x",
    "repo": "my-repo",
    "event_type": "build-release",
    "payload": {
        "version": "v1.0.0",
        "message": "Release build initiated",
        "環境": "本番"
    }
}

2. create_issue

Create a GitHub issue (useful as a fallback when dispatch fails).

Parameters:

• owner (string, required): Repository owner

• repo (string, required): Repository name

• title (string, required): Issue title

• body (string, optional): Issue description

• labels (array, optional): Issue labels (e.g., ["bug", "urgent"])

Example:

{
    "owner": "ai-info-x",
    "repo": "my-repo",
    "title": "Auto-generated notification",
    "body": "This issue was created as a fallback notification",
    "labels": ["automated", "notification"]
}

Response:

{
    "success": true,
    "message": "Issue created successfully",
    "issue_number": 42,
    "issue_url": "https://github.com/ai-info-x/my-repo/issues/42",
    "title": "Auto-generated notification"
}

3. get_repository_info

Retrieve comprehensive repository information.

Parameters:

• owner (string, required): Repository owner

• repo (string, required): Repository name

Example:

{
    "owner": "ai-info-x",
    "repo": "github-mcp-server"
}

Response:

{
    "success": true,
    "name": "github-mcp-server",
    "full_name": "ai-info-x/github-mcp-server",
    "description": "MCP Server with GitHub repository_dispatch API integration",
    "url": "https://github.com/ai-info-x/github-mcp-server",
    "clone_url_https": "https://github.com/ai-info-x/github-mcp-server.git",
    "clone_url_ssh": "git@github.com:ai-info-x/github-mcp-server.git",
    "private": false,
    "stars": 5,
    "forks": 2,
    "language": "Python",
    "default_branch": "main"
}

Testing

Run All Tests

pytest

Run with Coverage

pytest --cov=src --cov-report=html

Run Specific Test

pytest tests/test_github_mcp.py::TestTriggerRepositoryDispatch::test_trigger_dispatch_success -v

Project Structure

github-mcp-server/
├── src/
│   └── github_mcp_server.py       # Main MCP server implementation
├── tests/
│   └── test_github_mcp.py         # Test suite
├── README.md                      # This file
├── .env.template                  # Environment template
├── .gitignore                      # Git ignore rules
├── pyproject.toml                 # Project configuration & dependencies
└── .git/                           # Git repository

Development

Setting Up Development Environment

# Clone and install
git clone https://github.com/ai-info-x/github-mcp-server.git
cd github-mcp-server

# Create virtual environment (optional)
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev]"

Code Style

This project uses black for code formatting and flake8 for linting.

# Format code
black src/ tests/

# Check linting
flake8 src/ tests/

Type Checking

mypy src/

Error Handling

All tools return consistent JSON responses with success flag and error information:

Success Response:

{
    "success": true,
    "message": "Operation successful",
    ...
}

Error Response:

{
    "success": false,
    "error": "Error description",
    "status": 404
}

Common GitHub API errors:

• 404 Not Found: Repository or user doesn't exist

• 401 Unauthorized: Invalid or expired token

• 403 Forbidden: Insufficient permissions

• 422 Unprocessable Entity: Invalid payload or parameters

Troubleshooting

"GITHUB_TOKEN environment variable is required"

Ensure your token is set:

# Check if set
echo $GITHUB_TOKEN

# If not set, export it
export GITHUB_TOKEN="ghp_your_token_here"

"401 Unauthorized"

Your token may be invalid or expired:

1. Check token at https://github.com/settings/tokens

2. Regenerate if necessary

3. Update environment variable

"403 Forbidden"

Your token lacks required scopes:

1. Go to https://github.com/settings/tokens

2. Edit the token

3. Ensure repo and workflow scopes are enabled

"Repository not found"

Verify:

• Repository exists and is accessible

• Correct owner/repo names

• Owner is username (not organization) if querying user repos

Repository URLs

• GitHub: https://github.com/ai-info-x/github-mcp-server

• Clone (HTTPS): https://github.com/ai-info-x/github-mcp-server.git

• Clone (SSH): git@github.com:ai-info-x/github-mcp-server.git

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/your-feature)

3. Commit changes with clear messages

4. Write/update tests for new functionality

5. Ensure all tests pass (pytest)

6. Push to your fork

7. Create a Pull Request

Support

For issues, questions, or suggestions:

• Open an issue at https://github.com/ai-info-x/github-mcp-server/issues

• Check existing issues for similar problems

• Provide detailed reproduction steps

Changelog

v0.1.0 (Initial Release)

• ✨ Repository dispatch event triggering

• ✨ Issue creation with labels

• ✨ Repository information retrieval

• ✨ Japanese language support in payloads

• ✨ Comprehensive test suite

• 📝 Complete documentation