GitHub Actions Utils MCP Server - Connect AI tools directly to GitHub Actions

_{Created and maintained by techprimate and all the amazing contributors.}

Features • Tools • Installation • Configuration • Examples • Development • License

About

An MCP (Model Context Protocol) server that gives AI agents, assistants, and chatbots the ability to fetch and analyze GitHub Action definitions, explore available inputs and outputs, and understand action configurations—all through natural language interactions.

Use Cases:

Workflow Development: Quickly discover GitHub Action parameters while building CI/CD workflows
Action Discovery: Explore available inputs, outputs, and configuration options for any public GitHub Action
Documentation: Automatically generate documentation for actions used in your workflows
Migration & Updates: Understand parameter changes when upgrading action versions
Validation: Verify action configurations before deploying workflows

Features

Fetch GitHub Action parameters (get_action_parameters tool)
Fetch README documentation from GitHub repositories (get_readme tool)
Docker support for easy deployment
Cross-platform (macOS, Linux, Windows)
Works with VS Code, Claude Desktop, Cursor, Windsurf, and more

Tools

`get_action_parameters`

Fetches and parses a GitHub Action's action.yml file, returning complete metadata about inputs, outputs, and configuration.

Parameters:

actionRef (required): GitHub Action reference in format owner/repo@version

Example queries:

Can you show me the parameters for actions/checkout@v5?
What inputs does actions/setup-node@v4 accept?
Explain the outputs of docker/build-push-action@v6

`get_readme`

Fetches the README.md file from a GitHub repository for understanding action documentation.

Parameters:

repoRef (required): GitHub repository reference in format owner/repo[@ref] (defaults to main if no ref provided)

Example queries:

Can you get the README for actions/checkout?
Show me the documentation for docker/build-push-action@v6
What does the README say about github/github-mcp-server?

Example Workflows

Discovering Action Parameters

"What are all the inputs for actions/setup-python@v5?"

AI fetches and explains all available inputs including python-version, cache, architecture, etc.

Building a Workflow

"Help me create a workflow that checks out code, sets up Node.js 20, and runs tests"

AI uses both tools to understand the correct parameters and generate a complete workflow file.

Comparing Action Versions

"What changed between actions/upload-artifact@v3 and @v4?"

AI fetches both versions and highlights the differences in inputs, outputs, and behavior.

Exploring New Actions

"Show me how to use aws-actions/configure-aws-credentials"

AI uses get_readme to fetch documentation and get_action_parameters to understand all configuration options.

Installation

Prerequisites

A compatible MCP host application:
- VS Code 1.101+ with GitHub Copilot
- Claude Desktop
- Cursor IDE
- Windsurf IDE
- Any MCP-compatible client
One of the following:
- Pre-built binary (recommended)
- Docker
- Go 1.25+ (for building from source)

Quick Install

Option 1: Pre-built Binary (Recommended)

Download the latest release:

Visit GitHub Releases and download the appropriate binary for your platform:

macOS: github-actions-utils-cli-darwin-amd64 (Intel) or github-actions-utils-cli-darwin-arm64 (Apple Silicon)
Linux: github-actions-utils-cli-linux-amd64 or github-actions-utils-cli-linux-arm64
Windows: github-actions-utils-cli-windows-amd64.exe

Install:

# macOS/Linux - move to a directory in your PATH
sudo mv github-actions-utils-cli-* /usr/local/bin/github-actions-utils-cli
sudo chmod +x /usr/local/bin/github-actions-utils-cli

# Verify installation
github-actions-utils-cli --version

Option 2: Docker

# Pull the image (from GitHub Container Registry)
docker pull ghcr.io/techprimate/github-actions-utils-cli:latest

# Or from Docker Hub
docker pull docker.io/techprimate/github-actions-utils-cli:latest

# Test it works
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | docker run -i --rm ghcr.io/techprimate/github-actions-utils-cli:latest mcp

Option 3: Build from Source

# Clone and build
git clone https://github.com/techprimate/github-actions-utils-cli.git
cd github-actions-utils-cli
make build

# Binary will be at ./dist/github-actions-utils-cli

Configuration

VS Code with GitHub Copilot

Prerequisites: VS Code 1.101+ with GitHub Copilot installed

Setup:

Open VS Code settings (Cmd/Ctrl + ,)
Search for "MCP"
Click "Edit in settings.json"
Add the server configuration:

Using Binary

Using Docker

{
  "github.copilot.chat.mcp.servers": {
    "github-actions-utils": {
      "command": "/usr/local/bin/github-actions-utils-cli",
      "args": ["mcp"]
    }
  }
}

{
  "github.copilot.chat.mcp.servers": {
    "github-actions-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/techprimate/github-actions-utils-cli:latest",
        "mcp"
      ]
    }
  }
}

Restart VS Code
Open Copilot Chat and toggle "Agent mode" to activate MCP tools

Troubleshooting:

Ensure VS Code is version 1.101 or later
Verify GitHub Copilot extension is installed and activated
Check that the binary path is correct: which github-actions-utils-cli

Claude Desktop

Prerequisites: Claude Desktop installed

Setup:

Locate your Claude configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the server configuration:

Using Binary

Using Docker

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "/usr/local/bin/github-actions-utils-cli",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/techprimate/github-actions-utils-cli:latest",
        "mcp"
      ]
    }
  }
}

Restart Claude Desktop
Look for the 🔌 icon in the bottom right to verify the server is connected

Troubleshooting:

Verify the config file is valid JSON
Check Claude Desktop logs for connection errors
Ensure the binary path is absolute, not relative

Cursor IDE

Prerequisites: Cursor IDE installed

Setup:

Open Cursor Settings (Cmd/Ctrl + ,)
Navigate to "Cursor Settings" → "MCP"
Click "Edit Config"
Add the server configuration:

Using Binary

Using Docker

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "/usr/local/bin/github-actions-utils-cli",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/techprimate/github-actions-utils-cli:latest",
        "mcp"
      ]
    }
  }
}

Restart Cursor
The MCP tools will be available in the AI chat

Windsurf IDE

Prerequisites: Windsurf IDE installed

Setup:

Open Windsurf Settings
Navigate to "MCP Servers"
Add new server configuration:

Using Binary

Using Docker

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "/usr/local/bin/github-actions-utils-cli",
      "args": ["mcp"]
    }
  }
}

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/techprimate/github-actions-utils-cli:latest",
        "mcp"
      ]
    }
  }
}

Restart Windsurf

Other MCP Clients

For other MCP-compatible clients, use the standard MCP configuration format:

{
  "mcpServers": {
    "github-actions-utils": {
      "command": "/usr/local/bin/github-actions-utils-cli",
      "args": ["mcp"]
    }
  }
}

Refer to your MCP client's documentation for the specific configuration file location.

Telemetry

This project uses Sentry for error tracking and performance monitoring to help improve the tool.

Disable telemetry:

export TELEMETRY_ENABLED=false

Add this to your shell profile (.bashrc, .zshrc, etc.) to make it permanent.

Development

Prerequisites

Go 1.25 or later
Make
dprint (for formatting)

Setup

# Clone the repository
git clone https://github.com/techprimate/github-actions-utils-cli.git
cd github-actions-utils-cli

# Install dependencies
make init

# Build
make build

# Run tests
make test

# Format code
make format

# Run static analysis (vet, staticcheck, govulncheck)
make analyze

Project Structure

.
├── cmd/cli/              # CLI entry point with main.go
├── internal/
│   ├── cli/
│   │   ├── cmd/          # Cobra commands (root, mcp)
│   │   └── mcp/          # MCP server and tool handlers
│   ├── github/           # GitHub Actions fetcher and parser
│   └── logging/          # Multi-handler for Sentry integration
├── .github/workflows/    # CI/CD pipelines
├── docs/                 # Documentation
├── Makefile             # Build commands
└── README.md            # This file

Testing

# Run all tests
make test

# Run with coverage
go test -cover ./...

# Test specific package
go test ./internal/github/

# Run with race detection
go test -race ./...

Docker Development

Build and test Docker images locally:

# Build Linux binaries for Docker
make build-linux

# Build Docker image (multi-platform)
make docker-build

# Test the Docker image
make docker-test

# Run interactively
make docker-run

# Or use docker directly
docker run --rm -i ghcr.io/techprimate/github-actions-utils-cli:latest mcp

Docker Image Details:

Base Image: buildpack-deps:bookworm (includes common build tools and certificates)
Platforms: linux/amd64, linux/arm64
Registries:
- ghcr.io/techprimate/github-actions-utils-cli (GitHub Container Registry)
- docker.io/techprimate/github-actions-utils-cli (Docker Hub)
Tags:
- latest - Latest main branch build
- v1.0.0 - Specific version releases
- 1.0 - Major.minor version
- 1 - Major version

Manual Docker Build:

# Build binaries
make build-linux

# Build for specific platform
docker build --platform linux/amd64 -t github-actions-utils-cli:latest .

# Build multi-platform (requires buildx)
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t github-actions-utils-cli:latest \
  --load \
  .

Manual MCP Testing

Important: MCP servers communicate via JSON-RPC over stdin/stdout and are designed to be used by MCP clients, not directly from the command line. The server is working correctly when no output appears - it's waiting for proper JSON-RPC formatted input from an MCP client.

To verify the server is working:

# Build the CLI
make build

# Test that the server starts (it should produce an error about invalid message format)
echo '{}' | ./dist/github-actions-utils-cli mcp
# Output: Error: invalid message version tag ""; expected "2.0"
# This confirms the server is reading stdin and validating JSON-RPC messages

# Verify binary is executable
./dist/github-actions-utils-cli --version

To actually test the tools, configure the server in an MCP client (VS Code, Claude Desktop, Cursor, etc.) using the configuration examples above, then use natural language queries:

"Show me the parameters for actions/checkout@v5"
"Get the README for github/github-mcp-server"

The MCP client will handle the JSON-RPC communication and present results in a user-friendly format.

Adding New Tools

See AGENTS.md for detailed instructions on adding new MCP tools.

Quick overview:

Define arguments struct in internal/cli/mcp/tools.go
Implement handler function
Register tool in internal/cli/mcp/server.go
Add tests
Update README

Contributing

Contributions are welcome! Please see our contributing guidelines:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes using Conventional Commits
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Commit Message Format

We use Conventional Commits:

feat: add support for private actions
fix: handle action.yaml extension
docs: update installation instructions

Security

Reporting Security Issues

Please report security vulnerabilities to security@techprimate.com.

Security Best Practices

This tool only fetches publicly accessible GitHub Action definitions
No authentication tokens are required or stored
All network requests go through GitHub's public raw content CDN
Sentry telemetry can be disabled via environment variable

License

This project is licensed under the terms of the MIT License. See LICENSE for details.

Support

Made with ❤️ by techprimate

Name		Name	Last commit message	Last commit date
Latest commit History 18 Commits
.github		.github
cmd/cli		cmd/cli
docs		docs
internal		internal
.dockerignore		.dockerignore
.editorconfig		.editorconfig
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
Brewfile		Brewfile
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
dprint.json		dprint.json
go.mod		go.mod
go.sum		go.sum
renovate.json		renovate.json

Uh oh!

License

techprimate/github-actions-utils-cli

Folders and files

Latest commit

History

Repository files navigation

GitHub Actions Utils MCP Server - Connect AI tools directly to GitHub Actions

About

Features

Tools

get_action_parameters

get_readme

Example Workflows

Installation

Prerequisites

Quick Install

Option 1: Pre-built Binary (Recommended)

Option 2: Docker

Option 3: Build from Source

Configuration

VS Code with GitHub Copilot

Claude Desktop

Cursor IDE

Windsurf IDE

Other MCP Clients

Telemetry

Development

Prerequisites

Setup

Project Structure

Testing

Docker Development

Manual MCP Testing

Adding New Tools

Contributing

Commit Message Format

Security

Reporting Security Issues

Security Best Practices

License

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 5

Sponsor this project

Uh oh!

Languages

`get_action_parameters`

`get_readme`