GitHub MCP Tools

A Multi-Claude Program (MCP) for interacting with GitHub APIs through Claude Desktop.

Features

Search GitHub repositories and issues
Create, update, and manage GitHub issues and pull requests
Manage repository settings and configurations
Handle repository workflows and actions
Search for users and organizations
Manage repository collaborators and teams

Installation

Clone this repository:

git clone https://github.com/yourusername/github-mcp.git
cd github-mcp

Create and activate a virtual environment:

# On macOS/Linux
python -m venv venv
source venv/bin/activate

# On Windows
python -m venv venv
.\venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Create a .env file in the project root:
```
touch .env
```

Add your GitHub credentials to the .env file:

GITHUB_TOKEN=your_personal_access_token_here
GITHUB_USERNAME=your_github_username

Test the installation:

# Run all tests
python -m pytest

# Run a specific test file
python -m pytest tests/test_search_repos.py

Start the MCP server:
```
python run.py
```

Environment Setup

GitHub Personal Access Token

You'll need a fine-grained personal access token to authenticate with GitHub:

Log in to your GitHub account
Go to Settings > Developer settings > Personal access tokens > Fine-grained tokens
Click "Generate new token"
Configure the token:
- Token name: "Claude Desktop Integration"
- Description: "Token for Claude Desktop GitHub integration"
- Expiration: Choose an appropriate expiration date
- Repository access: Select "All repositories" or specific repositories
- Permissions:
  - Repository permissions:
    - Actions: Read and write
    - Contents: Read and write
    - Issues: Read and write
    - Pull requests: Read and write
    - Repository hooks: Read and write
    - Repository settings: Read and write
  - Organization permissions (if working with organization repositories):
    - Members: Read-only
    - Teams: Read-only
Click "Generate token" and save the generated token securely

Tools

Search Repositories

Search for GitHub repositories using various criteria.

Parameters:

query: Search query string
sort: Sort field (stars, forks, updated, etc.)
order: Sort order (asc or desc)
max_results: Maximum number of results to return (default: 10)

Create Issue

Create a new GitHub issue in a specified repository.

Parameters:

owner: Repository owner
repo: Repository name
title: Issue title
body: Issue description
labels: List of labels to apply
assignees: List of assignee usernames

Create Pull Request

Create a new pull request.

Parameters:

owner: Repository owner
repo: Repository name
title: PR title
body: PR description
head: Source branch
base: Target branch
draft: Whether to create as draft PR

Manage Repository Settings

Update repository settings and configurations.

Parameters:

owner: Repository owner
repo: Repository name
settings: Dictionary of settings to update

Search Issues

Search for issues across repositories.

Parameters:

query: Search query string
state: Issue state (open, closed, all)
sort: Sort field
order: Sort order
max_results: Maximum number of results

Manage Workflows

Manage GitHub Actions workflows.

Parameters:

owner: Repository owner
repo: Repository name
workflow_file: Workflow file path
action: Action to perform (enable, disable, trigger)

Manage Collaborators

Manage repository collaborators.

Parameters:

owner: Repository owner
repo: Repository name
username: Collaborator username
permission: Permission level (pull, push, admin, maintain, triage)

Example Usage

# Search for repositories
search_repos(query="python web framework", sort="stars", max_results=5)

# Create a new issue
create_issue(
    owner="username",
    repo="repository",
    title="Bug: Login not working",
    body="Users cannot log in using the login button",
    labels=["bug", "high-priority"]
)

# Create a pull request
create_pull_request(
    owner="username",
    repo="repository",
    title="Feature: Add user authentication",
    body="Implements JWT-based authentication",
    head="feature/auth",
    base="main"
)

# Search for issues
search_issues(query="is:open is:issue author:username", max_results=10)

# Manage repository settings
manage_repo_settings(
    owner="username",
    repo="repository",
    settings={
        "has_issues": True,
        "has_projects": True,
        "has_wiki": True
    }
)

Development

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src tests/

# Run specific test file
python -m pytest tests/test_search_repos.py

Adding New Tools

Create a new file in src/tools/
Implement your tool function
Register the tool in src/main.py
Add tests in tests/
Update documentation in README.md

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

License

MIT License

GitHub MCP Tools

A Multi-Claude Program (MCP) for interacting with GitHub APIs through Claude Desktop.

Features

Search GitHub repositories and issues
Create, update, and manage GitHub issues and pull requests
Manage repository settings and configurations
Handle repository workflows and actions
Search for users and organizations
Manage repository collaborators and teams

Installation

Clone this repository:

git clone https://github.com/yourusername/github-mcp.git
cd github-mcp

Create and activate a virtual environment:

# On macOS/Linux
python -m venv venv
source venv/bin/activate

# On Windows
python -m venv venv
.\venv\Scripts\activate

Install dependencies:
```
pip install -r requirements.txt
```
Create a .env file in the project root:
```
touch .env
```

Add your GitHub credentials to the .env file:

GITHUB_TOKEN=your_personal_access_token_here
GITHUB_USERNAME=your_github_username

Test the installation:

# Run all tests
python -m pytest

# Run a specific test file
python -m pytest tests/test_search_repos.py

Start the MCP server:
```
python run.py
```

Environment Setup

GitHub Personal Access Token

You'll need a fine-grained personal access token to authenticate with GitHub:

Log in to your GitHub account
Go to Settings > Developer settings > Personal access tokens > Fine-grained tokens
Click "Generate new token"
Configure the token:
- Token name: "Claude Desktop Integration"
- Description: "Token for Claude Desktop GitHub integration"
- Expiration: Choose an appropriate expiration date
- Repository access: Select "All repositories" or specific repositories
- Permissions:
  - Repository permissions:
    - Actions: Read and write
    - Contents: Read and write
    - Issues: Read and write
    - Pull requests: Read and write
    - Repository hooks: Read and write
    - Repository settings: Read and write
  - Organization permissions (if working with organization repositories):
    - Members: Read-only
    - Teams: Read-only
Click "Generate token" and save the generated token securely

Tools

Search Repositories

Search for GitHub repositories using various criteria.

Parameters:

query: Search query string
sort: Sort field (stars, forks, updated, etc.)
order: Sort order (asc or desc)
max_results: Maximum number of results to return (default: 10)

Create Issue

Create a new GitHub issue in a specified repository.

Parameters:

owner: Repository owner
repo: Repository name
title: Issue title
body: Issue description
labels: List of labels to apply
assignees: List of assignee usernames

Create Pull Request

Create a new pull request.

Parameters:

owner: Repository owner
repo: Repository name
title: PR title
body: PR description
head: Source branch
base: Target branch
draft: Whether to create as draft PR

Manage Repository Settings

Update repository settings and configurations.

Parameters:

owner: Repository owner
repo: Repository name
settings: Dictionary of settings to update

Search Issues

Search for issues across repositories.

Parameters:

query: Search query string
state: Issue state (open, closed, all)
sort: Sort field
order: Sort order
max_results: Maximum number of results

Manage Workflows

Manage GitHub Actions workflows.

Parameters:

owner: Repository owner
repo: Repository name
workflow_file: Workflow file path
action: Action to perform (enable, disable, trigger)

Manage Collaborators

Manage repository collaborators.

Parameters:

owner: Repository owner
repo: Repository name
username: Collaborator username
permission: Permission level (pull, push, admin, maintain, triage)

Example Usage

# Search for repositories
search_repos(query="python web framework", sort="stars", max_results=5)

# Create a new issue
create_issue(
    owner="username",
    repo="repository",
    title="Bug: Login not working",
    body="Users cannot log in using the login button",
    labels=["bug", "high-priority"]
)

# Create a pull request
create_pull_request(
    owner="username",
    repo="repository",
    title="Feature: Add user authentication",
    body="Implements JWT-based authentication",
    head="feature/auth",
    base="main"
)

# Search for issues
search_issues(query="is:open is:issue author:username", max_results=10)

# Manage repository settings
manage_repo_settings(
    owner="username",
    repo="repository",
    settings={
        "has_issues": True,
        "has_projects": True,
        "has_wiki": True
    }
)

Development

Running Tests

# Run all tests
python -m pytest

# Run with coverage
python -m pytest --cov=src tests/

# Run specific test file
python -m pytest tests/test_search_repos.py

Adding New Tools

Create a new file in src/tools/
Implement your tool function
Register the tool in src/main.py
Add tests in tests/
Update documentation in README.md

Contributing

Fork the repository
Create a feature branch
Make your changes
Run tests
Submit a pull request

License

MIT License