# @iiinigence/github-mcp

**Push commits, manage branches, open PRs, and read repos — by just asking your AI.**

An open-source [MCP](https://modelcontextprotocol.io) server for [GitHub](https://github.com), developed by [IIInigence](https://iiinigence.com). Works with Claude Desktop, Claude Code, and any MCP-compatible client.

Because it runs **on your machine with your token**, your AI assistant can ship code to GitHub even from cloud sandboxes that can't push directly — the API calls originate from your device, not the sandbox.

## Easiest install — one file, no terminal (Claude Desktop)

1. Download **`iiinie-github.mcpb`** from the [latest release](https://github.com/iiinigence/github-mcp/releases/latest)
2. In Claude Desktop: **Settings → Extensions → Advanced settings → Install Extension** → pick the downloaded file. Claude shows what you're getting; click **Install**.
3. Paste your GitHub token (see below) and optionally a default owner/org. Done.

Nervous about giving an AI push powers? Flip on **Read-only mode** in the same form: Claude can read repos and PRs but can't change a thing until you turn it off.

## Get a token (2 minutes)

Create a **fine-grained personal access token** at GitHub → Settings → [Developer settings → Fine-grained tokens](https://github.com/settings/personal-access-tokens/new):

- **Repository access**: *Only select repositories* — pick just the repos you want your AI to work with
- **Permissions → Repository permissions**:
  - Contents: **Read and write**
  - Pull requests: **Read and write**
  - Issues: **Read and write**
  - Actions: **Read-only**
  - Metadata: **Read-only** (added automatically)

Never use a classic token with broad scopes — fine-grained scoping is the whole safety story.

## Quick start (manual / npx route)

Add to Claude Desktop — Settings → Developer → Edit Config:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@iiinigence/github-mcp"],
      "env": {
        "GITHUB_TOKEN": "github_pat_your_token_here",
        "GITHUB_DEFAULT_OWNER": "your-username-or-org",
        "READ_ONLY": "false"
      }
    }
  }
}
```

Restart Claude Desktop, then try: *"Use whoami to check my GitHub connection, then list my repos."*

## Tools

15 tools. Tools marked 🔒 are destructive: the assistant is instructed to always get your explicit confirmation before calling them, and `READ_ONLY` blocks them entirely.

| Tool | What it does |
|------|--------------|
| `whoami` | Verify the token — who is authenticated |
| `list_repos` | Repositories the token can access, recently pushed first |
| `list_branches` | Branches with latest commit SHAs |
| `get_file` | Read a file (UTF-8) or list a directory at any ref |
| `list_commits` | Recent commits on a branch |
| `push_files` | **The core write tool** — commit multiple files to a branch in one commit and push. Creates the branch if needed. Never force-pushes. |
| `create_branch` | Create a branch from another branch |
| `delete_branch` 🔒 | Delete a branch (refuses the default branch) |
| `open_pr` | Open a pull request (normal or draft) |
| `list_prs` / `get_pr` | Browse PRs; details include changed files & mergeability |
| `merge_pr` 🔒 | Merge a PR (merge / squash / rebase) |
| `create_issue` | Open a new issue |
| `comment_on_issue` | Comment on an issue or PR |
| `list_workflow_runs` | Check GitHub Actions CI status after a push |

## Configuration

| Env var | Required | Description |
|---------|----------|-------------|
| `GITHUB_TOKEN` | ✅ | Fine-grained personal access token |
| `GITHUB_DEFAULT_OWNER` | — | Default owner/org when tools don't specify one |
| `READ_ONLY` | — | `true` = everything readable, all writes blocked (default `false`) |
| `GITHUB_BASE_URL` | — | Override for GitHub Enterprise (e.g. `https://github.example.com/api/v3`) |

## Safety notes

- Use a **fine-grained** token scoped to only the repos your AI should touch. Rotate it if it may have leaked.
- `push_files` never force-pushes, and `delete_branch` refuses the repository's default branch.
- Keep yourself as the approval step: have your assistant push to feature branches and open PRs you review, rather than committing to main.
- Start with `READ_ONLY: "true"` if you want to connect before granting write powers.

## Privacy

This connector runs locally, collects **no data**, has no telemetry, and talks only to GitHub's API. Your token is stored on your device by Claude Desktop and sent only to GitHub. Full policy: [PRIVACY.md](./PRIVACY.md).

## Who built this

[**IIInigence**](https://iiinigence.com) — a software development agency: custom software, AI automations, full platforms. This connector is part of our [video series](https://www.youtube.com/@iiinigence) on connecting Claude to your business tools, one at a time. See also our [SendGrid connector](https://github.com/iiinigence/sendgrid-mcp).

Want something like this built for your business? [Tell us what you'd build](https://get.iiinigence.io/contact).

## Development

```bash
git clone https://github.com/iiinigence/github-mcp.git
cd github-mcp
npm install
npm run build
GITHUB_TOKEN=github_pat_xxx node dist/index.js
```

MIT licensed. PRs welcome.

---

*This is an independent project by IIInigence. It is not affiliated with, endorsed, or sponsored by GitHub, Inc. "GitHub" is a trademark of GitHub, Inc., used here only to describe compatibility.*