GitHub Action Trigger MCP Server

A Model Context Protocol server for GitHub Actions integration.

Overview

This is a TypeScript-based MCP server designed for GitHub Actions integration. It provides the following features:

• Tool for fetching available GitHub Actions from a repository
• Tool for getting detailed information about a specific GitHub Action
• Tool for triggering GitHub workflow dispatch events
• Tool for fetching the latest releases from a GitHub repository

Features

Tools

• get_github_actions - Get available GitHub Actions for a repository
  • Required parameters: owner (repository owner, username or organization) and repo (repository name)
  • Optional parameters: token (GitHub personal access token, for accessing private repositories or increasing API rate limits)
  • Returns JSON data with workflow ID, name, path, state, URL, and content
• get_github_action - Get detailed information about a specific GitHub Action, including inputs and their requirements
  • Required parameters: owner (Action owner, username or organization) and repo (repository name of the action)
  • Optional parameters:
    • path: Path to the action definition file (default: 'action.yml')
    • ref: Git reference (branch, tag, or commit SHA, default: 'main')
    • token: GitHub personal access token (optional)
  • Returns detailed information about the Action, including name, description, author, inputs (and whether they're required), etc.
• trigger_github_action - Trigger a GitHub workflow and pass relevant parameters
  • Required parameters:
    • owner: Repository owner (username or organization)
    • repo: Repository name
    • workflow_id: The ID or filename of the workflow to trigger
  • Optional parameters:
    • ref: The git reference to trigger the workflow on (default: 'main')
    • inputs: Inputs to pass to the workflow (must match the workflow's defined inputs)
    • token: GitHub personal access token (must have the workflow scope)
  • Returns workflow run information, including status, URL, etc.
• get_github_release - Get the latest 2 releases from a GitHub repository
  • Required parameters: owner (repository owner, username or organization) and repo (repository name)
  • Optional parameters: token (GitHub personal access token, optional)
  • Returns information about the latest 2 releases

Installation

Recommended Installation: Using npx

The simplest way to install and use is via the npx command in your Claude Desktop configuration file without manual local installation:

Benefits of this method:

• No local package installation required
• Automatically uses the latest version
• Set up once and ready to use
• Built-in GitHub token configuration

Local Installation

If you prefer to install manually, follow these steps:

1. Install the package:

2. Use in Claude Desktop configuration:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

GitHub Token Configuration

To access the GitHub API, especially for private repositories or workflow triggers, you need to configure a GitHub personal access token. There are several ways to do this:

Method 1 (Recommended): Direct Configuration in Claude Desktop

Set the token directly in the Claude Desktop configuration file via the env field:

Method 2: Global Environment Variable

Set the GITHUB_TOKEN environment variable:

Method 3: Local Configuration File

Edit the configuration file:

Set your GitHub token:

A template for this configuration file is automatically created the first time the server starts.

Development

Install dependencies:

Build the server:

For automatic rebuilding during development:

Debugging

Use MCP Inspector for debugging:

The Inspector will provide a URL to access the debugging tools in your browser.

Publishing to npm

If you want to publish this package to npm, follow these steps:

1. Make sure you're logged in to npm and have permissions to publish to the @nextdrive organization:
   npm login
2. Build the project:
   npm run build
3. Publish to npm (organization-scoped packages are private by default, use --access public to make it public):
   npm publish --access public

After publishing, anyone can run this tool using the npx @nextdrive/github-action-trigger-mcp command or use it in their Claude Desktop configuration.

Usage Examples

Getting a List of GitHub Actions

Use the get_github_actions tool to get GitHub Actions for a repository:

If a default token is configured, it will be used automatically when accessing private repositories.

Example response:

Getting Detailed GitHub Action Information

Use the get_github_action tool to get detailed information about a specific Action:

Example response:

Triggering a GitHub Workflow

Use the trigger_github_action tool to trigger a GitHub workflow:

Example response:

Note: Triggering workflows requires:

1. The workflow must be configured to support the workflow_dispatch event
2. The GitHub token must have the workflow scope permission
3. Input parameters passed must match those defined in the workflow

Getting Latest Releases

Use the get_github_release tool to get the latest 2 releases from a repository:

Example response: