github-actions-mcp

GitHub Actions MCP Server

A Model Context Protocol (MCP) server that provides integration with GitHub Actions, allowing LLMs and tools like Cursor to interact with GitHub Actions workflows, runs, and artifacts.

Features

• List workflow runs for a repository
• View details of specific workflow runs
• Access workflow logs
• List and download artifacts
• Execute workflow dispatches
• Cancel or re-run workflows

Installation

From PyPI

pip install github-actions-mcp

From source

git clone https://github.com/yourusername/github-actions-mcp
cd github-actions-mcp
pip install -e .

MCP Requirement

This package depends on the Model Context Protocol (MCP) Python package. If MCP is not available, a mock implementation will be used for demonstration purposes, but full functionality will be limited.

To use the full functionality, install MCP:

pip install mcp>=1.2.0

Token Authentication

The server requires a GitHub Personal Access Token (PAT) with appropriate permissions for GitHub Actions:

• repo scope for private repositories
• workflow scope to trigger workflows

Set your token as an environment variable:

export GITHUB_TOKEN=your_token_here

Or use a .env file in your working directory containing:

GITHUB_TOKEN=your_token_here

Running with Claude Desktop

1. Install Claude Desktop
2. Edit your Claude Desktop configuration file:

{
  "mcpServers": {
    "github-actions": {
      "command": "github-actions-mcp",
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Running with Cursor or other MCP clients

Configure the client to use github-actions-mcp as the command to start the server.

MCP Features

Tools

• list-workflows: List all workflows in a repository
• list-workflow-runs: List recent workflow runs for a repository
• get-workflow-run: Get details about a specific workflow run
• list-artifacts: List artifacts for a workflow run
• download-artifact: Download a specific artifact
• dispatch-workflow: Trigger a workflow dispatch event
• cancel-workflow-run: Cancel a running workflow
• rerun-workflow: Re-run a workflow

Resources

• repo://{owner}/{repo}/workflows: List workflows for a repository
• repo://{owner}/{repo}/runs/{run_id}: Get details for a specific run
• repo://{owner}/{repo}/runs/{run_id}/logs: Get logs for a run
• repo://{owner}/{repo}/runs/{run_id}/artifacts: List artifacts for a run

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Examples

The package includes example scripts to help you get started:

Demo Script

The demo.py script demonstrates how to use the GitHub Actions MCP client to interact with GitHub Actions:

# Install required dependencies
pip install python-dotenv

# Set your GitHub token
export GITHUB_TOKEN=your_token_here

# Run the demo script with a repository
python -m github_actions_mcp.examples.demo octocat hello-world

This script will:

1. List all workflows in the specified repository
2. Get details about the first workflow
3. List recent runs for that workflow
4. List artifacts for the first run

When running with the mock MCP implementation, the script will use simulated data.

Alternatively, you can run the script directly:

# Run the demo script directly
python github_mcp/github_actions_mcp/examples/demo.py octocat hello-world