MCP GitHub Actions

A Deno-based MCP (Model Context Protocol) service that helps you securely reference GitHub Actions by providing:

Latest version lookup for any GitHub Action
Commit SHA retrieval for specific version tags
Immutability status checking for releases
Ready-to-use SHA-pinned references
Workflow analysis with update level detection (major/minor/patch)
Safe update suggestions that avoid breaking changes
Documentation retrieval for actions at specific versions
Version comparison to identify changes and breaking updates between releases

Why Use This?

GitHub Actions referenced by tag (e.g., actions/checkout@v4) can be vulnerable to supply chain attacks if the tag is moved to point to malicious code. This MCP service helps you:

Find the commit SHA for any action version
Check if a release is immutable (protected from modification)
Get secure references in the format owner/repo@sha # version

Installation

Prerequisites

Deno 2.x or later

Setup with Claude Desktop

Add to your Claude Desktop configuration (claude_desktop_config.json):

{
  "mcpServers": {
    "github-actions": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-env",
        "--allow-run=gh",
        "/path/to/mcp-github-actions/main.ts"
      ],
      "env": {
        "GITHUB_TOKEN": "your-github-token-optional"
      }
    }
  }
}

Setup with Claude Code CLI

claude mcp add github-actions -- deno run --allow-net --allow-env --allow-run=gh /path/to/mcp-github-actions/main.ts

Setup with Docker

The service is available as a Docker image using stdio transport.

Pull the image:

docker pull ghcr.io/tripletex/mcp-github-action:latest

Run directly:

docker run --rm -i -e GITHUB_TOKEN ghcr.io/tripletex/mcp-github-action:latest

Claude Desktop configuration:

{
  "mcpServers": {
    "github-actions": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "GITHUB_TOKEN",
        "ghcr.io/tripletex/mcp-github-action:latest"
      ],
      "env": {
        "GITHUB_TOKEN": "your-github-token-optional"
      }
    }
  }
}

Usage

Once configured, ask Claude to look up GitHub Actions:

Example prompts:

"Look up the latest version of actions/checkout"
"Get the secure reference for actions/setup-node@v4"
"Check if actions/cache@v4.2.0 is immutable"
"List all versions of actions/upload-artifact"
"Analyze my workflow file for outdated actions"
"Suggest safe updates for my CI workflow"
"What's the latest v4.x version of actions/checkout?"
"Show me the documentation for actions/checkout@v4"
"Compare changes between actions/setup-node@v4.0.0 and v6.0.0"

Tool: `lookup_action`

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Action reference (e.g., `actions/checkout` or `actions/checkout@v4`)
`include_all_versions`	boolean	No	List all available versions (default: false)

Example Output

Action: actions/checkout

Latest Version: v6.0.1
  Commit SHA: 8e8c483db84b4bee98b60c0593521ed34d9990e8
  Immutable: No
  Published: 2025-12-02T16:38:59Z

Recommended Usage (SHA-pinned):
  uses: actions/checkout@8e8c483db84b4bee98b60c0593521ed34d9990e8 # v6.0.1

Security Notes:
  - WARNING: This release is NOT immutable. The tag could potentially be moved to a different commit.
  - Using the SHA-pinned reference provides protection against tag tampering.
  - SHA-pinned references prevent supply chain attacks by ensuring you always use the exact same code.

Tool: `analyze_workflow`

Analyze a GitHub Actions workflow file and show version status for all actions. Reports current vs latest versions, update levels (major/minor/patch), and risk assessment.

Parameters

Parameter	Type	Required	Description
`workflow_content`	string	Yes	The workflow YAML content to analyze
`only_updates`	boolean	No	Only show actions that need updates (default: false)

Example Output

## Summary
Total actions: 6
Up to date: 1
Major updates available: 2 ⚠️
Minor updates available: 2
Patch updates available: 1

## Actions

| Action | Current | Latest | Update | Risk |
|--------|---------|--------|--------|------|
| actions/checkout | v4.2.2 | v6.0.1 | ⚠️ Major | 🔴 High |
| actions/setup-node | v4.1.0 | v6.2.0 | ⚠️ Major | 🔴 High |
| docker/login-action | v3.3.0 | v3.6.0 | 📦 Minor | 🟡 Medium |
| docker/build-push-action | v6.9.0 | v6.18.0 | 📦 Minor | 🟡 Medium |
| appleboy/ssh-action | v1.2.0 | v1.2.4 | 🔧 Patch | 🟢 Low |

## Safe Updates (Minor/Patch)
...

## Major Updates (Review Required)
...

Tool: `suggest_updates`

Suggest safe updates for GitHub Actions in a workflow. Returns only safe updates (minor/patch) and suggestions to stay current within major versions.

Parameters

Parameter	Type	Required	Description
`workflow_content`	string	Yes	The workflow YAML content to analyze
`risk_tolerance`	string	No	`"patch"` = only patches, `"minor"` = patch + minor (default), `"all"` = all

Example Output

## Summary
Total actions analyzed: 6
Already up to date: 1
Safe updates available: 3
Actions with major updates: 2 (staying on current major)

## Safe Updates
These updates are safe to apply:

### 📦 docker/login-action: v3.3.0 → v3.6.0
Minor version update - new features, backwards compatible

uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.6.0

### 🔧 appleboy/ssh-action: v1.2.0 → v1.2.4
Patch version update - bug fixes only

uses: appleboy/ssh-action@2ead5e36573714d0d3cfcbac3646c3e0f09ec849 # v1.2.4

## Updates Within Current Major
These actions have major updates available, but you can safely update within your current major version:

### actions/checkout: v4.2.2 → v4.2.2
Safe update within v4.x (latest overall is v6.0.1)

uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Tool: `get_latest_in_major`

Get the latest version of a GitHub Action within the same major version. Useful for safe updates that avoid breaking changes.

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Action reference with version (e.g., `actions/checkout@v4` or `@v4.1.0`)

Example Output

Action: actions/checkout
Current Version: v4
Major Version: v4

Latest in v4.x: v4.2.2
  Commit SHA: 11bd71901bbe5b1630ceea73d27597364c9af683
  Immutable: Yes

Note: Latest overall is v6.0.1

Recommended Usage (SHA-pinned):
  uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

Tool: `get_action_documentation`

Get README documentation for a GitHub Action at a specific version. Useful for understanding how to use an action at a particular release.

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Action reference (e.g., `actions/checkout` or `actions/checkout@v4`)
`ref`	string	No	Optional ref override (tag/branch/commit). Defaults to version or main branch

Example Output

# actions/checkout Documentation
Ref: v4.2.0

---

[Full README markdown content for the action at the specified version]

Tool: `compare_action_versions`

Compare changes between two versions of a GitHub Action. Shows release notes and identifies version update levels to help with upgrade decisions.

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	Action with current version (e.g., `actions/checkout@v4.0.2`)
`target_version`	string	No	Target version (defaults to latest)

Example Output

# Version Comparison: actions/checkout

From: v4.0.0
To: v4.2.0

## Summary
- Total releases: 3
- Major updates: 0
- Minor updates: 2
- Patch updates: 1

## Release History (chronological)

### v4.1.0 (2025-02-15) - Minor Update
Added support for sparse checkouts and improved performance.

### v4.1.1 (2025-02-20) - Patch Update
Fixed bug with submodule handling on Windows.

### v4.2.0 (2025-03-01) - Minor Update
Added new input parameter for custom checkout paths.

---

Note: Major version updates (marked with ⚠️) may contain breaking changes.
Review the release notes above to understand the impact of each update.

Authentication

The service supports multiple authentication methods, checked in the following order:

Org-specific tokens (GITHUB_TOKEN_<ORG>) - For multi-org scenarios
Environment variable (GITHUB_TOKEN) - Explicit token configuration
GitHub CLI (gh auth token) - Automatic token from logged-in gh CLI
Unauthenticated - Public repositories only with rate limits

Without Token (Unauthenticated)

Works for public repositories only
Rate limit: 60 requests/hour
No setup required

With GitHub CLI (Recommended for Development)

If you have the GitHub CLI installed and authenticated:

gh auth login

The service will automatically use your gh CLI token when no explicit token is configured. This is convenient for local development and doesn't require managing separate tokens.

Permissions note: The service needs --allow-run=gh permission to execute the gh command.

With Environment Token

Set the GITHUB_TOKEN environment variable:

Works for private repositories
Rate limit: 5,000 requests/hour
Required for organization private actions
Recommended for production deployments

Multi-Organization Support

For accessing private repositories across multiple organizations, configure org-specific tokens:

# Org-specific tokens (format: GITHUB_TOKEN_<ORG_NAME>)
# Hyphens in org names become underscores, all uppercase
GITHUB_TOKEN_MY_ORG=ghp_xxx...            # For My-Org
GITHUB_TOKEN_OTHER_ORG=ghp_yyy...         # For Other-Org
GITHUB_TOKEN=ghp_zzz...                    # Fallback for public repos

Token resolution order:

Org-specific token (GITHUB_TOKEN_<ORG>)
Fallback token (GITHUB_TOKEN)
GitHub CLI token (gh auth token)
Unauthenticated (public repos only)

Supported token types and required permissions:

Token Type	Required Permissions	Notes
Fine-grained PAT	`Contents: Read` + `Metadata: Read`	Recommended - scoped to specific repos/orgs
Classic PAT	`repo` scope	Broader access - use only if fine-grained isn't suitable
GitHub App	`Contents: Read`	Recommended for organizations

Note: For private repositories, the token must have read access to repository contents. Without proper permissions, you'll receive a 404 error when looking up private actions.

Example Claude Desktop config with multi-org:

{
  "mcpServers": {
    "github-actions": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-env",
        "--allow-run=gh",
        "/path/to/mcp-github-actions/main.ts"
      ],
      "env": {
        "GITHUB_TOKEN_MY_ORG": "ghs_xxx...",
        "GITHUB_TOKEN_OTHER_ORG": "ghs_yyy...",
        "GITHUB_TOKEN": "ghp_zzz..."
      }
    }
  }
}

Configuration

Minimum Release Age

To avoid using releases that are too new (which may contain undiscovered bugs or be part of a supply chain attack), you can configure a minimum age requirement:

# Skip releases published within the last 5 days
MIN_RELEASE_AGE_DAYS=5

When set, the service will:

Skip the absolute latest release if it's newer than the threshold
Return the most recent release that meets the age requirement
Display the release age in the output
Add a note in security notes when filtering is active

Example with minimum age:

Action: actions/checkout

Latest Version: v6.0.1
  Commit SHA: 8e8c483db84b4bee98b60c0593521ed34d9990e8
  Immutable: No
  Published: 2025-12-02T16:38:59Z (52 days ago)

Security Notes:
  - Minimum release age filter active: only considering releases at least 5 days old.

If no release meets the age requirement, an error will be returned indicating the latest release's age.

Claude Desktop config with minimum age:

{
  "mcpServers": {
    "github-actions": {
      "command": "deno",
      "args": [
        "run",
        "--allow-net",
        "--allow-env",
        "--allow-run=gh",
        "/path/to/mcp-github-actions/main.ts"
      ],
      "env": {
        "GITHUB_TOKEN": "ghp_xxx...",
        "MIN_RELEASE_AGE_DAYS": "5"
      }
    }
  }
}

Development

# Run the server
deno task start

# Run with watch mode (auto-reload)
deno task dev

# Type check
deno task check

# Lint
deno task lint

# Format
deno task fmt

# Compile to binary
deno task compile

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
.github/workflows		.github/workflows
src		src
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmrc		.npmrc
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
deno.json		deno.json
deno.lock		deno.lock
main.ts		main.ts

License

mediazone/mcp-github-action

Folders and files

Latest commit

History

Repository files navigation

MCP GitHub Actions

Why Use This?

Installation

Prerequisites

Setup with Claude Desktop

Setup with Claude Code CLI

Setup with Docker

Usage

Tool: lookup_action

Parameters

Example Output

Tool: analyze_workflow

Parameters

Example Output

Tool: suggest_updates

Parameters

Example Output

Tool: get_latest_in_major

Parameters

Example Output

Tool: get_action_documentation

Parameters

Example Output

Tool: compare_action_versions

Parameters

Example Output

Authentication

Without Token (Unauthenticated)

With GitHub CLI (Recommended for Development)

With Environment Token

Multi-Organization Support

Configuration

Minimum Release Age

Development

Security Best Practices

References

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Packages 0

Languages

Tool: `lookup_action`

Tool: `analyze_workflow`

Tool: `suggest_updates`

Tool: `get_latest_in_major`

Tool: `get_action_documentation`

Tool: `compare_action_versions`

Packages