github-actions-versions-mcp

README

github-actions-versions-mcp

A Model Context Protocol server that reports the latest released versions of GitHub Actions, using the GitHub REST API. Ask your MCP client "is actions/checkout@v3 up to date?" and it will tell you the newest release and whether your pin is stale.

Written in Go, speaks MCP over stdio, so it can be launched directly by clients such as Claude Code and Claude Desktop.

> Check the actions in .github/workflows/ci.yml

  actions/checkout          v7  → v7.0.1   major-pinned
  actions/setup-go          v7  → v7.0.0   major-pinned
  golangci/golangci-lint-…  v9  → v9.3.0   major-pinned
  5 action(s) found, 0 outdated.

Tools

Tool	Arguments	Returns
latest_release	owner, repo	Latest release: tag_name, published_at, html_url, prerelease, plus pinning advice. Uses GET /repos/{owner}/{repo}/releases/latest.
list_releases	owner, repo, limit (default 10)	The most recent releases, newest first. Uses GET /repos/{owner}/{repo}/releases.
check_workflow_actions	content (workflow YAML)	For every uses: action, whether the pinned ref is the latest release, with a per-action status.

Version status semantics

check_workflow_actions classifies each pinned ref:

• up-to-date — pinned to the exact latest release tag (e.g. @v4.2.2).
• major-pinned — pinned to a major tag (e.g. @v4) that still resolves to the latest release. Recommended: you keep receiving patch/minor updates automatically.
• pinned-sha — pinned to a commit SHA (most secure against supply-chain attacks).
• outdated — a newer release exists (includes branch pins like @main).
• unknown — no releases found, or the repo does not exist. Some actions ship tags without GitHub releases.

Download

Every release ships pre-built binaries — there is nothing to compile. Open the latest release and download the file matching your system:

System	Chip	File
Linux	Intel / AMD	gha-mcp_<version>_linux_amd64.tar.gz
Linux	ARM (Raspberry Pi, Ampere)	gha-mcp_<version>_linux_arm64.tar.gz
macOS	Apple Silicon (M1–M4)	gha-mcp_<version>_darwin_arm64.tar.gz
macOS	Intel	gha-mcp_<version>_darwin_amd64.tar.gz
Windows	Intel / AMD	gha-mcp_<version>_windows_amd64.zip
Windows	ARM	gha-mcp_<version>_windows_arm64.zip

Not sure which chip you have? On macOS run uname -m (arm64 or x86_64); on Linux run uname -m (aarch64 or x86_64); on Windows check Settings → System → About → System type.

Debian, Fedora and Alpine users can skip the archive and install a system package instead — see Linux packages below.

Install

Linux and macOS

# 1. extract (adjust the filename to what you downloaded)
tar -xzf gha-mcp_*_linux_amd64.tar.gz

# 2. install onto your PATH
sudo install -m 755 gha-mcp /usr/local/bin/gha-mcp

# 3. check it works
gha-mcp --version

On macOS the binary is not code-signed, so Gatekeeper quarantines it. Clear that once, after installing:

xattr -dr com.apple.quarantine /usr/local/bin/gha-mcp

No root access? Extract anywhere and use the absolute path in your MCP client config — the server never needs to be on your PATH.

Windows

# 1. extract into a folder you control
Expand-Archive .\gha-mcp_*_windows_amd64.zip -DestinationPath "$env:LOCALAPPDATA\Programs\gha-mcp"

# 2. add that folder to your user PATH (new terminals pick it up)
[Environment]::SetEnvironmentVariable(
  "Path",
  [Environment]::GetEnvironmentVariable("Path", "User") + ";$env:LOCALAPPDATA\Programs\gha-mcp",
  "User")

# 3. check it works (in a NEW terminal)
gha-mcp --version

The binary is unsigned, so SmartScreen may warn on first run — choose More info → Run anyway, or skip PATH entirely and point your MCP client at the full path to gha-mcp.exe.

Linux packages

Prefer your package manager? Download the .deb, .rpm or .apk for your architecture from the latest release:

sudo dpkg -i gha-mcp_*_linux_amd64.deb                     # Debian / Ubuntu
sudo rpm -i gha-mcp_*_linux_amd64.rpm                      # Fedora / RHEL / openSUSE
sudo apk add --allow-untrusted gha-mcp_*_linux_amd64.apk   # Alpine

These install gha-mcp to /usr/bin, already on your PATH.

Verifying your download

Every release includes checksums.txt and an SBOM per archive. Verifying is optional but takes a second — download checksums.txt into the same folder:

sha256sum -c checksums.txt --ignore-missing        # Linux
shasum -a 256 -c checksums.txt --ignore-missing    # macOS

# Windows — compare the printed hash against the matching line in checksums.txt
Get-FileHash .\gha-mcp_1.0.0_windows_amd64.zip -Algorithm SHA256

Homebrew and Scoop

Not available yet. Both are configured in .goreleaser.yaml but disabled, because publishing to a tap or bucket needs a personal access token this project does not use today.

From source

Requires the Go version declared in go.mod.

go install github.com/pcpl2/github-actions-versions-mcp@latest   # installs as github-actions-versions-mcp
# or
git clone https://github.com/pcpl2/github-actions-versions-mcp
cd github-actions-versions-mcp
go build -o gha-mcp .

Verify the install:

gha-mcp --version

Configure your MCP client

Claude Code

claude mcp add github-actions -- gha-mcp

Use an absolute path instead of gha-mcp if the binary is not on your PATH. To raise the API rate limit, pass a token through:

claude mcp add github-actions --env GITHUB_TOKEN=ghp_xxx -- gha-mcp

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "github-actions": {
      "command": "/absolute/path/to/gha-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    }
  }
}

Authentication & rate limits

The server works anonymously (60 requests/hour). Set the GITHUB_TOKEN environment variable to a personal access token (no scopes needed for public repos) to raise the limit to 5000 requests/hour. When the limit is hit, the tool returns a clear error explaining how to raise it.

check_workflow_actions makes one API call per distinct action, so a large workflow can exhaust the anonymous budget in a few runs.

Pinning recommendations

In a real workflow, prefer:

1. A commit SHA (@1a2b3c…) for maximum supply-chain security, or
2. A major tag (@v4) for automatic patch/minor updates.

Avoid pinning to a branch like @main — it is not reproducible and can change under you.

Development

go test ./...            # unit + in-memory integration tests (no network required)
go vet ./...
golangci-lint run ./...  # config in .golangci.yml

Tests use httptest for the GitHub client and an in-memory MCP transport for the tools, so the suite is fully offline and deterministic.

See CLAUDE.md for the architecture notes and project conventions.

Releasing

Releases are triggered manually, never by pushing a tag:

Actions → Release → Run workflow, then fill in the version (v1.2.3) and hit the button.

The tag is a result of the run, not its trigger: .github/workflows/release.yml validates the version, runs the tests, creates the tag locally, builds linux/darwin/windows × amd64/arm64 with GoReleaser, and only then pushes the tag and publishes the GitHub Release via softprops/action-gh-release. A failed build leaves no tag on origin.

Input	Default	Effect
version	—	The tag to create, e.g. v1.2.3. Rejected if malformed or already taken.
prerelease	false	Marks the release as a pre-release.
draft	false	Creates the release as a draft for you to publish by hand.
dry_run	false	Builds and uploads the artifacts as a workflow artifact, without tagging or releasing.

Everything runs on the built-in GITHUB_TOKEN — no secrets to configure. Publishing the Homebrew cask and Scoop manifest is the one thing that would need a personal access token, which is why both are disabled in .goreleaser.yaml.

Validate config changes locally before running the workflow:

goreleaser check
goreleaser release --snapshot --clean --skip=publish,announce

Contributing

Issues and pull requests are welcome. Please keep the test suite offline, run golangci-lint run ./... before opening a PR, and use Conventional Commits (feat:, fix:, …) — release notes are generated from them.

Found a security problem? Please do not open a public issue — follow SECURITY.md instead.

License

BSD 2-Clause © Patryk Ławicki

Documentation

Overview

Command gha-mcp is a Model Context Protocol server that reports the latest released versions of GitHub Actions, using the GitHub REST API.

It speaks MCP over stdio, so it can be launched directly by MCP clients such as Claude Desktop and Claude Code.

Set the GITHUB_TOKEN environment variable to raise the GitHub API rate limit from 60 to 5000 requests per hour.