Git-Free Mode

Overview

Git-Free Mode allows the GitHub MCP Server to function on systems without Git installed, providing 48 of 83 tools via the GitHub API.

Perfect for:

• macOS without Xcode Command Line Tools
• Windows systems without Git for Windows
• Restricted environments (containers, cloud shells)
• CI/CD runners with minimal tooling
• Systems where Git installation is blocked by policy

How It Works

Automatic Detection

On startup, the server:

1. Checks for Git CLI: Runs git --version
2. If Git found: All 83 tools available (full mode)
3. If Git not found: Filters out 35 Git tools, keeps 48 API/admin tools

No manual configuration needed — detection is automatic.

Tool Availability

Category	With Git	Without Git	Notes
Git Operations	34	0	Requires Git CLI
GitHub API	8	8	✅ Fully available
Dashboard & Response	10	10	✅ Fully available
Repair Tools	6	6	✅ Fully available
Administrative	22	22	✅ Fully available
Hybrid Tools	3	2	push_files requires Git CLI (stays disabled)
Total	83	48	58% available

What You Lose

Without Git, these operations are not available:

• Local Git status and file operations
• Committing, pushing, pulling, branching
• Merge, rebase, conflict resolution
• Stash, remote management, tags
• Git log analysis and diff operations

What You Keep

All GitHub API and administrative operations remain fully functional:

✅ Repository Management

• List repositories
• Create repositories
• Repository settings and configuration

✅ Pull Request Operations

• List PRs
• Create PRs
• Comment on PRs
• Review PRs
• Merge PRs

✅ Issue Management

• Comment on issues
• Close issues
• View assigned issues

✅ Dashboard & Triage

• Dashboard overview
• Notifications
• Security alerts
• Failed workflows

✅ Administrative Controls (v3.0)

• Repository settings
• Branch protection
• Webhooks
• Collaborators
• Teams

✅ File Operations (Git-Free Alternative)

• List repository contents
• Download files
• Download entire repository
• Update repository (API-based pull)

File Operations Without Git

Four tools provide Git-like operations via GitHub API.

github_list_repo_contents

Browse repository files without cloning.

Example:

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

Output: Directory listing with file/folder structure.

github_download_file

Download individual file from repository.

Example:

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

Use case: Fetch specific config files, scripts, or documentation.

github_download_repo

Clone entire repository via API (no Git required).

Example:

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

How it works:

1. Downloads repository as ZIP archive
2. Extracts to destination directory
3. No .git folder (not a Git repository)

Limitations:

• No Git history
• No branch tracking
• Larger download size than git clone

Performance

For very large repositories (>500MB), this can be slow. Consider using Git if available.

github_pull_repo

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

Example:

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

How it works:

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

Use case: Keep a local copy synchronized without Git.

Hybrid Tools in Git-Free Mode

create_file and update_file

These tools automatically switch to API mode when Git is unavailable.

Git mode (with Git installed):

{
  "path": "src/main.go",
  "content": "package main\n..."
}

→ Creates file locally (instant, 0 API tokens)

API mode (without Git):

{
  "path": "src/main.go",
  "content": "package main\n...",
  "owner": "username",
  "repo": "my-project",
  "branch": "main",
  "commit_message": "feat: Add main.go"
}

→ Creates file via GitHub API (requires additional parameters)

push_files

Disabled in Git-Free Mode because it requires local Git for staging, committing, and pushing in one call.

Workflows in Git-Free Mode

Browse and Download Repository

1. "List contents of facebook/react"
   → github_list_repo_contents

2. "Download the README.md file"
   → github_download_file

3. "Download the entire repository to ./react-source"
   → github_download_repo

Make Changes Without Local Git

1. "Download my repository to ./my-project"
   → github_download_repo

2. [Edit files locally in your editor]

3. "Update src/main.go in my repository with the new code"
   → update_file (API mode with full parameters)

Triage and Respond

1. "Show me my GitHub dashboard"
   → github_dashboard

2. "List open PRs for my-org/backend-api"
   → github_list_prs

3. "Comment on PR #123: 'Looks good!'"
   → github_comment_pr

4. "Merge PR #123 using squash"
   → github_merge_pr

Administrative Operations

1. "List collaborators on my-org/frontend-app"
   → github_list_collaborators

2. "Add user john-doe as a collaborator with push access"
   → github_add_collaborator

3. "Update branch protection rules on main"
   → github_update_branch_protection

Installing Git (If Desired)

To enable full functionality, install Git:

Windows

Download from: git-scm.com/download/win

Or use Chocolatey:

choco install git

macOS

Option 1: Xcode Command Line Tools (recommended)

xcode-select --install

Option 2: Homebrew

brew install git

Linux

Debian/Ubuntu:

sudo apt update && sudo apt install git

Fedora/RHEL:

sudo dnf install git

Arch:

sudo pacman -S git

After installation, restart Claude Desktop for the server to detect Git.

Performance Considerations

API Rate Limits

Git-Free Mode relies entirely on GitHub API:

• Authenticated: 5,000 requests/hour
• File operations: Consume 1-3 requests each
• Large repos: github_download_repo can use multiple requests

Best practices:

• Use github_download_file for single files (1 request)
• Avoid repeatedly downloading large repos
• Cache downloaded repositories locally

Network Usage

Operation	Git Mode	Git-Free Mode
Clone 100MB repo	~100MB	~100MB (similar)
Pull 10 changed files	~50KB	~1MB (re-downloads full files)
View file content	0 bytes (local)	~file size (API fetch)

Recommendation: If you frequently work with repositories, install Git for efficiency.

Limitations

Cannot Do Without Git

• ❌ Local branching and commits
• ❌ Merge and rebase operations
• ❌ Conflict resolution
• ❌ Stash management
• ❌ Git history navigation
• ❌ Blame/annotate
• ❌ Cherry-pick

Workarounds

Git Operation	Git-Free Alternative
View file history	Use GitHub web interface
Create branch	Use GitHub API (create ref)
Commit changes	Use update_file API mode
View diffs	Download files, compare locally
Merge branches	Create PR, then github_merge_pr

Detecting Git Availability

Check if Git is detected:

"Is Git available on this system?"

Server responds with:

{
  "git_available": false,
  "tools_available": 48,
   "tools_unavailable": 35,
  "mode": "git-free"
}

Or:

{
  "git_available": true,
  "git_version": "2.39.0",
   "tools_available": 83,
  "mode": "full"
}

Comparison: Git vs. Git-Free Mode

Feature	Git Mode	Git-Free Mode
Setup	Requires Git installation	No dependencies
Tools available	83 (100%)	48 (58%)
Performance	Instant local operations	API latency ~100-500ms
Network usage	Minimal (only push/pull)	Every operation hits API
Offline capability	✅ Local Git works	❌ Requires internet
API rate limits	Minimal impact	Significant impact
Best for	Active development	Triage, admin, CI/CD

Recommendation

Install Git if:

• You actively develop locally
• You work with large repositories
• You need branching/merging
• You want offline capability

Use Git-Free Mode if:

• Git installation blocked/prohibited
• Only need triage and admin operations
• Working in restricted environment
• Temporary system without Git

Frequently Asked Questions

Can I switch between modes?

Yes. Install Git and restart Claude Desktop — the server automatically detects Git and enables all 83 tools.

Do I lose any administrative features?

No. All 22 admin tools work identically in Git-Free Mode.

Can I still create pull requests?

Yes. Use github_create_pr (GitHub API tool, no Git required).

What about private repositories?

Fully supported. Your GitHub token provides access to private repos via API.

Is there a performance penalty?

Yes. API operations have ~100-500ms latency vs. instant local Git. But for occasional operations, this is acceptable.