Neura Market
Back to .md Directory
TOOLS.md

MCP GitHub Tools Documentation

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

fblettner
May 2, 2026
0 downloads
1 views
ai mcp
View source

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
  2. File Operations
  3. Branching & Commits
  4. Issues Management
  5. Pull Requests
  6. Code & Issue Search
  7. 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:

{
  "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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

{
  "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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

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

Squash merge with custom message:

{
  "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:

{
  "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:

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

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

{
  "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:

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

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

{
  "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:

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

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

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

Related Documents

TOOLS.md

🛠 Tools

A curated list of tools (and tips on how to use them) that will level up your bounty game. For more, head [back to the main page](./README.md).

ai
0
2
bugcrowd
TOOLS.md

Setup and Tools Overview

Generally, if you are running Glue from a docker image, we have tried to

ai
0
2
OWASP
TOOLS.md

Function Calling / Tool Use

Function calling (also referred to as tool use or function invocation) enables language models (LLMs) to execute predefined actions or functions outside of their internal capabilities. Different AI model vendors may refer to this feature using various terms such as **Function Calling**, **Tool Use**, **Plugins**, or **Function Invocation**.

aillm
0
1
chabicht
TOOLS.md

htmltools (development version)

* Fix test for testthat 3.3.0. (#442)

airag
0
1
wurli