GitHub API Tools

Overview

12 tools that operate directly against the GitHub API: repositories, pull requests, and file operations without requiring Git locally. They require a personal access token and consume API rate limits, so prefer local Git tools when available.

Repository Management (4)

github_list_repos

List all repositories accessible to your GitHub token.

Parameters:

• type (optional): Filter by type (all, owner, public, private, member)
• sort (optional): Sort by (created, updated, pushed, full_name)
• limit (optional): Maximum repositories to return (default: 30)

Example:

{
  "type": "owner",
  "sort": "updated",
  "limit": 10
}

Output:

{
  "total": 42,
  "repositories": [
    {
      "name": "my-project",
      "full_name": "username/my-project",
      "private": false,
      "description": "A cool project",
      "url": "https://github.com/username/my-project",
      "language": "Go",
      "stars": 15,
      "forks": 3,
      "updated_at": "2 hours ago"
    }
  ]
}

github_create_repo

Create a new GitHub repository.

Parameters:

• name (required): Repository name
• description (optional): Repository description
• private (optional): Create as private repository (default: false)
• auto_init (optional): Initialize with README (default: false)
• gitignore_template (optional): Language template (e.g., Go, Node, Python)
• license_template (optional): License type (e.g., mit, apache-2.0, gpl-3.0)

Example:

{
  "name": "new-api-server",
  "description": "RESTful API server in Go",
  "private": false,
  "auto_init": true,
  "gitignore_template": "Go",
  "license_template": "mit"
}

Output:

{
  "name": "new-api-server",
  "full_name": "username/new-api-server",
  "url": "https://github.com/username/new-api-server",
  "clone_url": "https://github.com/username/new-api-server.git",
  "ssh_url": "git@github.com:username/new-api-server.git"
}

github_list_prs

List pull requests for a repository.

Parameters:

• owner (required): Repository owner (username or organization)
• repo (required): Repository name
• state (optional): Filter by state (open, closed, all)
• sort (optional): Sort by (created, updated, popularity, long-running)
• limit (optional): Maximum PRs to return (default: 30)

Example:

{
  "owner": "facebook",
  "repo": "react",
  "state": "open",
  "sort": "updated",
  "limit": 5
}

github_create_pr

Create a new pull request.

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• title (required): PR title
• head (required): Source branch (your feature branch)
• base (required): Target branch (usually main or develop)
• body (optional): PR description (supports Markdown)
• draft (optional): Create as draft PR (default: false)

Example:

{
  "owner": "username",
  "repo": "my-project",
  "title": "Add user authentication",
  "head": "feature-auth",
  "base": "main",
  "body": "## Summary\n- Implements OAuth2 flow\n- Adds login/logout endpoints\n\n## Test Plan\n- [ ] Test login with GitHub\n- [ ] Test logout\n- [ ] Test token refresh",
  "draft": false
}

Output:

{
  "number": 42,
  "title": "Add user authentication",
  "url": "https://github.com/username/my-project/pull/42",
  "state": "open",
  "author": "username",
  "created_at": "just now"
}

File Operations (4) — Git-Free Mode

Access repository files via GitHub API without Git CLI.

When to use

Perfect for environments without Git installed (e.g., macOS without Xcode Command Line Tools, restricted systems, CI/CD containers).

github_list_repo_contents

List files and directories in a repository path.

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• path (optional): Directory path (default: root /)
• ref (optional): Branch/tag/commit (default: default branch)

Example:

{
  "owner": "torvalds",
  "repo": "linux",
  "path": "drivers/net",
  "ref": "master"
}

Output:

{
  "path": "drivers/net",
  "items": [
    {
      "name": "ethernet",
      "type": "dir",
      "size": 0
    },
    {
      "name": "wireless",
      "type": "dir",
      "size": 0
    },
    {
      "name": "Makefile",
      "type": "file",
      "size": 1523
    }
  ]
}

github_download_file

Download a single file from GitHub repository.

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• path (required): File path in repository
• ref (optional): Branch/tag/commit (default: default branch)
• destination (optional): Local save path (default: current directory with same name)

Example:

{
  "owner": "golang",
  "repo": "go",
  "path": "README.md",
  "destination": "./golang-README.md"
}

Output:

{
  "file": "README.md",
  "size": 1234,
  "saved_to": "./golang-README.md",
  "sha": "abc123..."
}

github_download_repo

Clone entire repository via GitHub API (no Git required).

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• ref (optional): Branch/tag/commit (default: default branch)
• destination (required): Local directory to save repository

Example:

{
  "owner": "microsoft",
  "repo": "vscode",
  "ref": "main",
  "destination": "./vscode-source"
}

Large repositories

This downloads the entire repo as a ZIP archive and extracts it. For very large repos (>500MB), this can be slow and consume significant bandwidth.

Output:

{
  "repository": "microsoft/vscode",
  "ref": "main",
  "destination": "./vscode-source",
  "files_extracted": 12456,
  "total_size_mb": 234.5
}

github_pull_repo

Update local directory with latest changes from GitHub (API-based “pull”).

Parameters:

• owner (required): Repository owner
• repo (required): Repository name
• ref (optional): Branch/tag/commit (default: default branch)
• destination (required): Local directory (must already exist from previous github_download_repo)

Example:

{
  "owner": "microsoft",
  "repo": "vscode",
  "ref": "main",
  "destination": "./vscode-source"
}

What it does:

1. Compares local files with remote repository
2. Downloads only changed/new files
3. Removes deleted files
4. Updates metadata

Output:

{
  "repository": "microsoft/vscode",
  "ref": "main",
  "files_updated": 12,
  "files_added": 3,
  "files_removed": 1,
  "total_changes": 16
}

Hybrid Tools (3)

Smart tools that use local Git first, fallback to GitHub API.

create_file

Create a new file in repository.

Behavior:

1. If in Git repository: Creates file locally (0 tokens)
2. If not in Git repo: Creates via GitHub API

Parameters:

• path (required): File path
• content (required): File content
• commit_message (optional): Commit message (API mode only)
• owner (optional): Repository owner (API mode only)
• repo (optional): Repository name (API mode only)
• branch (optional): Target branch (API mode only)

Example (Git mode):

{
  "path": "src/utils/logger.go",
  "content": "package utils\n\nfunc Log(msg string) {\n\t// TODO\n}"
}

Example (API mode):

{
  "path": "src/utils/logger.go",
  "content": "package utils\n\nfunc Log(msg string) {\n\t// TODO\n}",
  "commit_message": "feat: Add logger utility",
  "owner": "username",
  "repo": "my-project",
  "branch": "main"
}

update_file

Update existing file in repository.

Behavior:

1. If in Git repository: Updates file locally (0 tokens)
2. If not in Git repo: Updates via GitHub API

Parameters: Same as create_file

Best practice

When possible, work in a local Git repository for instant, free operations. Use API mode only when necessary (remote-only editing, automation scripts, etc.).

push_files

Batch-write multiple files and complete git add -A + git commit + git push in a single call.

Behavior:

1. Git required: Uses local Git only; fails fast if no Git/workspace (git_set_workspace first).
2. Writes each file (create or update), stages all changes, commits with your message, and pushes to the current branch (or override).

Parameters:

• files (required): Array of {path, content} objects
• message (required): Commit message
• branch (optional): Target branch (defaults to current branch)

Example (batch push):

{
  "files": [
    {"path": "src/new/handler.go", "content": "package new\n"},
    {"path": "README.md", "content": "Updated docs"}
  ],
  "message": "feat: batch doc + handler",
  "branch": "main"
}

Why use it? Reduces 20+ tool calls (create → add → commit → push per file) to a single, atomic operation.

API Rate Limits

GitHub API has rate limits you should be aware of:

Account Type	Requests/Hour
Authenticated	5,000
Unauthenticated	60

Your current token is authenticated, so you have 5,000 requests per hour.

Check your rate limit

"What's my current GitHub API rate limit?"

The server tracks and reports rate limit status.

Common Workflows

Create and Setup New Repository

1. "Create a new private repository called 'my-api'"
   → github_create_repo

2. "Clone it to ./my-api directory"
   → github_download_repo

3. [Work locally with Git tools]

4. "Push changes"
   → git_push

Review PRs Without Cloning

1. "List open PRs for facebook/react"
   → github_list_prs

2. "Download README.md from PR #12345"
   → github_download_file with specific ref

3. "Comment on PR #12345"
   → github_comment_pr (see Dashboard tools)

Git-Free Workflow

1. "Download microsoft/vscode to ./vscode"
   → github_download_repo

2. [Make changes in editor]

3. "Update the file README.md in my repository"
   → update_file (API mode)

4. "Pull latest changes to ./vscode"
   → github_pull_repo

When to Use Which Tool

Scenario	Recommended Tool
List your repositories	github_list_repos
Create new repository	github_create_repo
Clone repository (with Git)	Local: git clone + Git tools
Clone repository (without Git)	github_download_repo
View repository files	github_list_repo_contents
Download single file	github_download_file
Update repository (without Git)	github_pull_repo
Create pull request	github_create_pr
List pull requests	github_list_prs
Edit file locally	Git tools (update_file in Git mode)
Edit file remotely	update_file in API mode

Responsible use

API actions modify remote repositories. Confirm owners, repositories, branches, and refs before making changes. We are not responsible for misuse or resulting damage.