🔌 github-mcp-connector

Talk to GitHub from an MCP-speaking agent.

A single static Go binary that speaks the Model Context Protocol and exposes 18 tools for working with GitHub: repositories, branches, commits, file contents, issues, pull requests, and search.

No Python, no uv, no runtime dependency to install — just a binary and an .mcp.json.

✨ Why this exists

An agent that can only talk about your GitHub repos isn't that useful. This gives it hands: it can read and write files in a repo, open and triage issues, push a branch and open a PR, and merge it — all against the real GitHub API, with the same guardrails (size caps, friendly errors, destructive-action annotations) as the sibling connectors.

🧰 Tools

Tool	What it does	Write?
`github_whoami`	Get the user authenticated by `GITHUB_TOKEN`
`github_list_repos`	List repos for a user/org, or the authenticated user
`github_get_repo`	Get one repository's details
`github_create_repo`	Create a new repository	✍️
`github_list_branches`	List branches in a repository
`github_list_commits`	List commits, optionally filtered by branch/path
`github_get_file_contents`	Read a file's content, or list a directory
`github_create_or_update_file`	Create/update a file via a commit (≤ 5 MB)	✍️
`github_list_issues`	List issues in a repository
`github_get_issue`	Get one issue's full details
`github_create_issue`	Create a new issue	✍️
`github_update_issue`	Update an issue's title/body/state/labels	✍️
`github_add_issue_comment`	Comment on an issue or PR	✍️
`github_list_pull_requests`	List pull requests
`github_get_pull_request`	Get one PR's full details, incl. diff stats
`github_create_pull_request`	Open a pull request	✍️
`github_merge_pull_request`	Merge a pull request	🗑️ destructive
`github_search_repositories`	Search repositories with GitHub search qualifiers

Every tool accepts an optional response_format: markdown (default, pretty tables for a chat UI) or json (for programmatic use).

🚀 Quickstart

Fastest path: grab a prebuilt bundle from the latest release — download github-mcp-connector-plugin-<version>-<os>-<arch>.zip, unzip it, and point Cowork/Claude at the plugin/ folder inside (see step 4 of SETUP.md). No Go toolchain required.

From source:

# 1. Build
cd go-server
go mod tidy
go build -o github-connector-server .
cp github-connector-server ../plugin/servers/go/

# 2. Set up auth — a personal access token, see SETUP.md
export GITHUB_TOKEN=ghp_...

# 3. Run
./go-server/github-connector-server   # serves MCP over stdio

Or make build — see the Makefile for every shortcut (test, vet, fmt, lint, tidy).

Full walkthrough — including wiring this up as a Claude/Cowork plugin — is in SETUP.md.

🔐 Configuration

Everything is environment variables, passed through by the plugin's .mcp.json:

Variable	Purpose	Default
`GITHUB_TOKEN`	Personal access token (classic or fine-grained). Needs `repo`/`public_repo` and `read:org` scopes depending on what you use it for.	— (required)
`GITHUB_API_URL`	GitHub Enterprise Server API base URL, e.g. `https://github.example.com/api/v3`.	(unset — github.com)

🧪 Quality bar

This isn't a toy script — it's got the same checks you'd expect from a production Go service:

✅ Unit tests for every input-validation path (go test ./...)
✅ go vet + gofmt clean
✅ golangci-lint (govet, staticcheck, errcheck, gosec, and more)
✅ govulncheck — no known vulnerabilities in the dependency graph
✅ CodeQL static security analysis on every push
✅ End-to-end verified — every tool (repos, branches, commits, file read/write, issues, comments, PRs, merge, search) was exercised against a real, dedicated GitHub sandbox repo, not mocks
✅ Dependabot keeps Go modules and Actions current

All of it runs in CI on every push and PR.

🏷️ Releases & versioning

Versions follow semver and are cut automatically by release-please from Conventional Commits on main:

fix: ... → patch (v0.1.0 → v0.1.1)
feat: ... → minor (v0.1.1 → v0.2.0)
feat!: ... / BREAKING CHANGE: footer → major (v0.2.0 → v1.0.0)

Every merged PR updates a standing "chore(main): release vX.Y.Z" PR with an auto-generated CHANGELOG.md. Merging that PR:

tags the release and publishes it on GitHub
builds and attaches zipped, ready-to-install plugin bundles for linux/darwin/windows × amd64/arm64
regenerates server.json from those exact assets (fresh version + SHA-256 hashes) and publishes it to the official MCP Registry via mcp-publisher, authenticated with GitHub OIDC — no stored secrets

See .github/workflows/release-please.yml and .github/workflows/publish-mcp-registry.yml (also runnable by hand for an existing tag via workflow_dispatch).

📁 Layout

github-mcp-connector/
├── README.md                  ← you are here
├── SETUP.md                   ← step-by-step setup guide
├── CONTRIBUTING.md             ← how to contribute
├── CODE_OF_CONDUCT.md
├── SECURITY.md                 ← vulnerability reporting
├── CODEOWNERS
├── LICENSE                     ← MIT
├── Makefile                    ← build / test / lint shortcuts
├── .golangci.yml                ← lint rules
├── release-please-config.json  ← semver/changelog automation config
├── .release-please-manifest.json
├── server.json                  ← MCP Registry manifest (regenerated fresh per release by CI)
├── scripts/
│   └── render-server-json.sh    ← rebuilds server.json from a release's zip assets
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                     ← build, vet, test, lint, govulncheck
│   │   ├── codeql.yml                 ← security scanning
│   │   ├── pr-title.yml               ← Conventional Commits PR title check
│   │   ├── release-please.yml         ← version PRs, tagging, GitHub releases
│   │   ├── publish-mcp-registry.yml   ← publishes server.json to the MCP Registry
│   │   └── rebuild-release-assets.yml ← manual re-attach fallback
│   ├── ISSUE_TEMPLATE/
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml
├── go-server/                  ← the MCP server source
│   ├── main.go
│   ├── main_test.go
│   ├── go.mod / go.sum
│   └── README.md
└── plugin/                     ← installable Cowork/Claude plugin
    ├── .claude-plugin/plugin.json
    ├── .mcp.json                ← holds credentials locally — never commit real ones
    └── servers/go/              ← compiled binary goes here

🤝 Contributing

PRs and issues are very welcome — see CONTRIBUTING.md for the full guide (setup, coding conventions, how to add a new tool) and the Code of Conduct.

main is protected: every change, including the maintainer's, lands via pull request with CI green. PR titles must follow Conventional Commits — that's what drives the automatic versioning above.

Found a security issue? Please follow SECURITY.md instead of opening a public issue.

github mcp connector