MCP GitHub Tools Documentation

# MCP GitHub Tools Documentation

Complete reference guide for all available GitHub MCP (Model Context Protocol) tools with usage examples.

---

## Table of Contents

1. [Repository Management](#repository-management)
2. [File Operations](#file-operations)
3. [Branching & Commits](#branching--commits)
4. [Issues Management](#issues-management)
5. [Pull Requests](#pull-requests)
6. [Code & Issue Search](#code--issue-search)
7. [User Search](#user-search)

---

## Repository Management

### 1. Create Repository
Create a new GitHub repository in your account.

**Function:** `create_repository`

**Parameters:**
- `name` (required): Repository name
- `description` (optional): Repository description
- `private` (optional): Whether the repository should be private (default: false)
- `autoInit` (optional): Initialize with README.md (default: false)

**Usage Examples:**

```json
{
  "name": "my-awesome-project",
  "description": "An awesome project for learning",
  "private": false,
  "autoInit": true
}
```

**Response includes:**
- Repository ID, name, owner details
- URLs (HTML, SSH, clone)
- Created/updated timestamps

---

### 2. Fork Repository
Fork a GitHub repository to your account or specified organization.

**Function:** `fork_repository`

**Parameters:**
- `owner` (required): Repository owner (username or organization)
- `repo` (required): Repository name
- `organization` (optional): Organization to fork to (defaults to personal account)

**Usage Examples:**

```json
{
  "owner": "torvalds",
  "repo": "linux"
}
```

```json
{
  "owner": "microsoft",
  "repo": "vscode",
  "organization": "my-organization"
}
```

---

### 3. Search Repositories
Search for GitHub repositories.

**Function:** `search_repositories`

**Parameters:**
- `query` (required): Search query (supports GitHub search syntax)
- `perPage` (optional): Number of results per page (default: 30, max: 100)
- `page` (optional): Page number for pagination (default: 1)

**Usage Examples:**

```json
{
  "query": "language:python stars:>1000 topic:machine-learning",
  "perPage": 50,
  "page": 1
}
```

```json
{
  "query": "user:torvalds",
  "perPage": 10
}
```

---

## File Operations

### 4. Get File Contents
Retrieve the contents of a file or directory from a GitHub repository.

**Function:** `get_file_contents`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `path` (required): Path to the file or directory
- `branch` (optional): Branch to get contents from (defaults to default branch)

**Usage Examples:**

```json
{
  "owner": "facebook",
  "repo": "react",
  "path": "README.md"
}
```

```json
{
  "owner": "kubernetes",
  "repo": "kubernetes",
  "path": "docs",
  "branch": "main"
}
```

---

### 5. Create or Update File
Create or update a single file in a GitHub repository.

**Function:** `create_or_update_file`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `path` (required): Path where to create/update the file
- `content` (required): Content of the file
- `message` (required): Commit message
- `branch` (required): Branch to create/update the file in
- `sha` (required for updates): SHA of the file being replaced

**Usage Examples:**

Creating a new file:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "path": "docs/getting-started.md",
  "content": "# Getting Started\n\nThis guide will help you get started...",
  "message": "Add getting started guide",
  "branch": "main"
}
```

Updating an existing file:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "path": "README.md",
  "content": "# Updated README",
  "message": "Update README with new information",
  "branch": "main",
  "sha": "e69de29bb2d1d6434b8b29ae775ad8c2e48c5391"
}
```

---

### 6. Push Multiple Files
Push multiple files to a GitHub repository in a single commit.

**Function:** `push_files`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `branch` (required): Branch to push to
- `files` (required): Array of files to push
  - `path`: File path
  - `content`: File content
- `message` (required): Commit message

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "branch": "main",
  "message": "Add project documentation files",
  "files": [
    {
      "path": "docs/README.md",
      "content": "# Documentation\n\nWelcome to our documentation."
    },
    {
      "path": "docs/guide.md",
      "content": "# User Guide\n\nFollow these steps..."
    },
    {
      "path": "CHANGELOG.md",
      "content": "# Changelog\n\n## Version 1.0.0\n- Initial release"
    }
  ]
}
```

---

## Branching & Commits

### 7. Create Branch
Create a new branch in a GitHub repository.

**Function:** `create_branch`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `branch` (required): Name for the new branch
- `from_branch` (optional): Source branch to create from (defaults to default branch)

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "branch": "feature/add-authentication"
}
```

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "branch": "bugfix/fix-login-error",
  "from_branch": "develop"
}
```

---

### 8. List Commits
Get list of commits of a branch in a GitHub repository.

**Function:** `list_commits`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `sha` (optional): SHA of a specific commit or branch
- `page` (optional): Page number for pagination
- `perPage` (optional): Results per page

**Usage Examples:**

```json
{
  "owner": "torvalds",
  "repo": "linux",
  "sha": "main",
  "perPage": 20,
  "page": 1
}
```

```json
{
  "owner": "nodejs",
  "repo": "node",
  "page": 2
}
```

---

## Issues Management

### 9. Create Issue
Create a new issue in a GitHub repository.

**Function:** `create_issue`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `title` (required): Issue title
- `body` (optional): Issue description
- `assignees` (optional): Array of usernames to assign
- `labels` (optional): Array of label names
- `milestone` (optional): Milestone number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "title": "Bug: Login page not responding",
  "body": "## Description\nThe login page is not responding on Firefox.\n\n## Steps to reproduce\n1. Open the site\n2. Navigate to login\n3. Try to enter credentials\n\n## Expected behavior\nThe login form should be responsive.",
  "labels": ["bug", "high-priority"],
  "assignees": ["octocat"]
}
```

```json
{
  "owner": "facebook",
  "repo": "react",
  "title": "Feature request: Add TypeScript support",
  "body": "It would be great to have better TypeScript support.",
  "labels": ["enhancement"]
}
```

---

### 10. List Issues
List issues in a GitHub repository with filtering options.

**Function:** `list_issues`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `state` (optional): Issue state - "open", "closed", or "all" (default: "open")
- `labels` (optional): Array of label names to filter by
- `sort` (optional): Sort by - "created", "updated", or "comments" (default: "created")
- `direction` (optional): Sort direction - "asc" or "desc"
- `since` (optional): Only show issues updated after this date (ISO 8601)
- `page` (optional): Page number
- `per_page` (optional): Results per page

**Usage Examples:**

```json
{
  "owner": "facebook",
  "repo": "react",
  "state": "open",
  "labels": ["bug", "high-priority"],
  "sort": "created",
  "direction": "desc",
  "per_page": 30
}
```

```json
{
  "owner": "kubernetes",
  "repo": "kubernetes",
  "state": "closed",
  "sort": "updated",
  "since": "2024-01-01T00:00:00Z"
}
```

---

### 11. Get Issue
Get details of a specific issue in a GitHub repository.

**Function:** `get_issue`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `issue_number` (required): Issue number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "issue_number": 42
}
```

---

### 12. Update Issue
Update an existing issue in a GitHub repository.

**Function:** `update_issue`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `issue_number` (required): Issue number
- `title` (optional): New title
- `body` (optional): New description
- `state` (optional): New state - "open" or "closed"
- `assignees` (optional): Array of usernames
- `labels` (optional): Array of label names
- `milestone` (optional): Milestone number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "issue_number": 42,
  "state": "closed",
  "body": "Fixed in PR #123"
}
```

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "issue_number": 42,
  "title": "Bug: Updated title",
  "labels": ["bug", "fixed"],
  "assignees": ["octocat", "github"]
}
```

---

### 13. Add Issue Comment
Add a comment to an existing issue.

**Function:** `add_issue_comment`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `issue_number` (required): Issue number
- `body` (required): Comment text

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "issue_number": 42,
  "body": "I've started working on this issue. Will have a PR ready by Friday."
}
```

```json
{
  "owner": "kubernetes",
  "repo": "kubernetes",
  "issue_number": 123,
  "body": "Closing as duplicate of #456"
}
```

---

## Pull Requests

### 14. Create Pull Request
Create a new pull request in a GitHub repository.

**Function:** `create_pull_request`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `title` (required): Pull request title
- `head` (required): Branch with changes (feature branch)
- `base` (required): Target branch (usually "main" or "develop")
- `body` (optional): Pull request description
- `draft` (optional): Create as draft (default: false)
- `maintainer_can_modify` (optional): Allow maintainers to modify (default: false)

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "title": "Add authentication feature",
  "head": "feature/authentication",
  "base": "main",
  "body": "## Description\nThis PR adds JWT-based authentication.\n\n## Changes\n- Added JWT token generation\n- Added token validation middleware\n- Added login endpoint\n\n## Testing\nAdded unit tests for all new functions.",
  "draft": false
}
```

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "title": "Work in progress: Database migration",
  "head": "feature/db-migration",
  "base": "develop",
  "draft": true,
  "maintainer_can_modify": true
}
```

---

### 15. List Pull Requests
List and filter repository pull requests.

**Function:** `list_pull_requests`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `state` (optional): PR state - "open", "closed", or "all" (default: "open")
- `head` (optional): Filter by head user or organization and branch
- `base` (optional): Filter by base branch name
- `sort` (optional): Sort by - "created", "updated", "popularity", or "long-running"
- `direction` (optional): Sort direction - "asc" or "desc"
- `page` (optional): Page number
- `per_page` (optional): Results per page

**Usage Examples:**

```json
{
  "owner": "facebook",
  "repo": "react",
  "state": "open",
  "sort": "updated",
  "direction": "desc",
  "per_page": 20
}
```

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "state": "all",
  "base": "main",
  "sort": "created"
}
```

---

### 16. Get Pull Request
Get details of a specific pull request.

**Function:** `get_pull_request`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347
}
```

---

### 17. Get Pull Request Files
Get the list of files changed in a pull request.

**Function:** `get_pull_request_files`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number

**Usage Examples:**

```json
{
  "owner": "facebook",
  "repo": "react",
  "pull_number": 28234
}
```

**Response includes:**
- File paths
- Status (added, modified, deleted, renamed, etc.)
- Number of additions/deletions
- Patch information

---

### 18. Get Pull Request Status
Get the combined status of all status checks for a pull request.

**Function:** `get_pull_request_status`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347
}
```

**Response includes:**
- Overall status (success, failure, pending)
- Individual check statuses
- Check descriptions and URLs

---

### 19. Update Pull Request Branch
Update a pull request branch with the latest changes from the base branch.

**Function:** `update_pull_request_branch`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number
- `expected_head_sha` (optional): Expected SHA of the PR's HEAD ref

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347
}
```

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347,
  "expected_head_sha": "6dcb09b5b57875f7f3c8c5e2e55d5e3b5f5c5e5e"
}
```

---

### 20. Get Pull Request Reviews
Get the reviews on a pull request.

**Function:** `get_pull_request_reviews`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number

**Usage Examples:**

```json
{
  "owner": "kubernetes",
  "repo": "kubernetes",
  "pull_number": 89234
}
```

**Response includes:**
- Review ID, author, and timestamp
- Review state (PENDING, APPROVED, COMMENTED, DISMISSED)
- Review body/comments

---

### 21. Get Pull Request Comments
Get the review comments on a pull request.

**Function:** `get_pull_request_comments`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number

**Usage Examples:**

```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347
}
```

**Response includes:**
- Comment ID, author, and timestamp
- Comment body
- File and line information
- Comment links

---

### 22. Create Pull Request Review
Create a review on a pull request.

**Function:** `create_pull_request_review`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number
- `body` (required): The body text of the review
- `event` (required): Review action - "APPROVE", "REQUEST_CHANGES", or "COMMENT"
- `commit_id` (optional): SHA of the commit that needs review
- `comments` (optional): Array of inline comments
  - `path` (required): File path being commented on
  - `position` OR `line` (required): Position or line number
  - `body` (required): Comment text

**Usage Examples:**

Simple approval:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347,
  "body": "Looks good to me! The implementation is clean and follows our coding standards.",
  "event": "APPROVE"
}
```

Request changes:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347,
  "body": "Please address the comments below before merging.",
  "event": "REQUEST_CHANGES",
  "comments": [
    {
      "path": "src/main.js",
      "line": 42,
      "body": "This variable name is unclear. Please rename to something more descriptive."
    },
    {
      "path": "test/main.test.js",
      "line": 10,
      "body": "Add a test case for the error scenario."
    }
  ]
}
```

Comment only:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347,
  "body": "I have some suggestions for improvement.",
  "event": "COMMENT",
  "comments": [
    {
      "path": "docs/README.md",
      "line": 5,
      "body": "Consider adding a section about installation instructions."
    }
  ]
}
```

---

### 23. Merge Pull Request
Merge a pull request.

**Function:** `merge_pull_request`

**Parameters:**
- `owner` (required): Repository owner
- `repo` (required): Repository name
- `pull_number` (required): Pull request number
- `merge_method` (optional): Merge method - "merge", "squash", or "rebase" (default: "merge")
- `commit_title` (optional): Title for the automatic commit message
- `commit_message` (optional): Extra detail to append to commit message

**Usage Examples:**

Simple merge:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347
}
```

Squash merge with custom message:
```json
{
  "owner": "octocat",
  "repo": "Hello-World",
  "pull_number": 1347,
  "merge_method": "squash",
  "commit_title": "Add authentication feature",
  "commit_message": "Implements JWT-based authentication with token refresh capability"
}
```

Rebase merge:
```json
{
  "owner": "facebook",
  "repo": "react",
  "pull_number": 28234,
  "merge_method": "rebase"
}
```

---

## Code & Issue Search

### 24. Search Code
Search for code across GitHub repositories.

**Function:** `search_code`

**Parameters:**
- `q` (required): Search query (supports GitHub search syntax)
- `per_page` (optional): Results per page (default: 30, max: 100)
- `page` (optional): Page number for pagination
- `order` (optional): Sort order - "asc" or "desc" (default: "desc")

**Usage Examples:**

```json
{
  "q": "function handleClick language:javascript",
  "per_page": 20,
  "order": "desc"
}
```

```json
{
  "q": "const API_KEY in:file language:python user:octocat",
  "page": 1
}
```

```json
{
  "q": "TODO org:facebook",
  "per_page": 50
}
```

---

### 25. Search Issues
Search for issues and pull requests across GitHub repositories.

**Function:** `search_issues`

**Parameters:**
- `q` (required): Search query (supports GitHub search syntax)
- `sort` (optional): Sort by - "comments", "reactions", "reactions-+1", "reactions--1", "reactions-smile", "reactions-thinking_face", "reactions-heart", "reactions-tada", "interactions", "created", or "updated"
- `order` (optional): Sort order - "asc" or "desc"
- `per_page` (optional): Results per page (default: 30, max: 100)
- `page` (optional): Page number

**Usage Examples:**

```json
{
  "q": "is:issue is:open label:bug created:>2024-01-01",
  "sort": "updated",
  "order": "desc",
  "per_page": 30
}
```

```json
{
  "q": "is:pr is:merged author:octocat repo:facebook/react",
  "sort": "created",
  "per_page": 20
}
```

```json
{
  "q": "is:issue state:closed type:issue language:python reactions:>5",
  "sort": "reactions-+1"
}
```

---

## User Search

### 26. Search Users
Search for users on GitHub.

**Function:** `search_users`

**Parameters:**
- `q` (required): Search query (can include name, location, followers, etc.)
- `sort` (optional): Sort by - "followers", "repositories", or "joined"
- `order` (optional): Sort order - "asc" or "desc"
- `per_page` (optional): Results per page (default: 30, max: 100)
- `page` (optional): Page number

**Usage Examples:**

```json
{
  "q": "location:San Francisco followers:>1000",
  "sort": "followers",
  "order": "desc",
  "per_page": 30
}
```

```json
{
  "q": "type:user language:python",
  "sort": "repositories"
}
```

```json
{
  "q": "octocat",
  "page": 1
}
```

---

## Common Use Cases & Workflows

### Workflow 1: Complete Issue Resolution
1. **Search Issues**: `search_issues` - Find related issues
2. **Get Issue**: `get_issue` - Get detailed information
3. **Create Branch**: `create_branch` - Create feature branch
4. **Create Pull Request**: `create_pull_request` - Submit changes
5. **Create Review**: `create_pull_request_review` - Review code
6. **Merge PR**: `merge_pull_request` - Merge to main
7. **Update Issue**: `update_issue` - Close and reference PR

### Workflow 2: Documentation Update
1. **Get File Contents**: `get_file_contents` - Check existing docs
2. **Create or Update File**: `create_or_update_file` - Update documentation
3. **Create Pull Request**: `create_pull_request` - Submit for review
4. **Get PR Status**: `get_pull_request_status` - Check if ready to merge

### Workflow 3: Code Review
1. **Get Pull Request**: `get_pull_request` - Get PR details
2. **Get PR Files**: `get_pull_request_files` - See what changed
3. **Get PR Comments**: `get_pull_request_comments` - Review comments
4. **Create Review**: `create_pull_request_review` - Submit review

---

## Notes

- All functions require proper authentication
- Timestamps are in ISO 8601 format
- Arrays and objects should be properly formatted as JSON
- GitHub API rate limits may apply
- Some operations require appropriate permissions