gha-intel-mcp

npm version License: MIT

npm · Source · Issues

Inspect GitHub Actions run timing and review workflow configuration through MCP.

Tools

Requirements

• Node.js >= 18 (uses native fetch)
• A GitHub token with access to the repositories you want to inspect. See your token type and endpoint permissions before granting access.

Setup

Three transport modes are available. Choose whichever fits your deployment:

Option A: stdio (local, recommended for desktop clients)

The server runs as a subprocess of the MCP client over stdin/stdout. No network port required.

{
  "mcpServers": {
    "gha-intel": {
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

claude mcp add gha-intel -e GITHUB_TOKEN=ghp_your_token -- npx -y @barissozudogru/gha-intel-mcp

{
  "mcpServers": {
    "gha-intel": {
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "gha-intel": {
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

{
  "servers": {
    "gha-intel": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

{
  "mcpServers": {
    "gha-intel": {
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

mcpServers:
  - name: gha-intel
    command: npx
    args:
      - -y
      - "@barissozudogru/gha-intel-mcp"
    env:
      GITHUB_TOKEN: ghp_your_token

{
  "context_servers": {
    "gha-intel": {
      "command": {
        "path": "npx",
        "args": ["-y", "@barissozudogru/gha-intel-mcp"],
        "env": {
          "GITHUB_TOKEN": "ghp_your_token"
        }
      }
    }
  }
}

{
  "mcpServers": {
    "gha-intel": {
      "command": "npx",
      "args": ["-y", "@barissozudogru/gha-intel-mcp"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Option B: HTTP (remote or cloud clients)

Start the server in HTTP mode and point clients at the endpoint:

GITHUB_TOKEN=ghp_your_token npx @barissozudogru/gha-intel-mcp --http
# Server listens on http://0.0.0.0:3000/mcp
# Health check: http://localhost:3000/health

Or set via environment variable instead of the flag:

TRANSPORT=http PORT=3000 GITHUB_TOKEN=ghp_your_token npx @barissozudogru/gha-intel-mcp

{
  "mcpServers": {
    "gha-intel": {
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "servers": {
    "gha-intel": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

{
  "mcpServers": {
    "gha-intel": {
      "serverUrl": "http://localhost:3000/mcp"
    }
  }
}

mcpServers:
  - name: gha-intel
    url: http://localhost:3000/mcp

Option C: Docker

docker build -t gha-intel-mcp .
docker run -p 3000:3000 -e GITHUB_TOKEN=ghp_your_token gha-intel-mcp

The container starts in HTTP mode by default. Point your client at http://localhost:3000/mcp.

Tool Reference

list_workflow_performance

Fetch real run timing data and compute job-level statistics.

Output: Per-job and per-step timing stats (avg, min, max, p95), overall run timing, and a list of recent run conclusions.

analyze_workflow_config

Parse and audit a workflow YAML for optimisation opportunities.

Output: Findings grouped by severity (critical / warning / info / good) across nine categories, each with a concrete recommendation.

Categories analysed: Dependency caching, matrix strategy and fail-fast, concurrency groups and cancel-in-progress, artifact uploads, git checkout depth, job timeout-minutes, runner version pinning, Docker layer caching, and trigger path filters.

get_billing_usage

Retrieve repository cache consumption and recent run estimates. Account billing is currently limited by a retired API integration.

Output: With repo supplied, cache usage and recent run timing where accessible. Account billing requests use retired GitHub endpoints and can fail. Existing cost estimates use a historical rate table and should not be treated as current charges.

Environment Variables

Limitations and deployment

• Account billing uses /settings/billing/actions, which GitHub retired in September 2025. Granting broader token scopes does not restore those endpoints. Repository cache and run timing requests use separate endpoints.
• Current cost estimates use historical rates, and cache utilisation assumes a fixed 10 GB limit. Review account configuration before using either for capacity or budget decisions.
• HTTP mode listens on all interfaces and does not implement client authentication. Keep it on a trusted network or place an authenticated gateway in front of it. The server uses its configured GitHub token for client requests.
• Timing statistics describe the fetched runs, rather than predicting a future run.

Development and support

Report problems through GitHub issues. See CONTRIBUTING.md for the contribution workflow.

To build and test a source checkout with Node.js 22:

npm ci
npm test
npm run build

The default branch can contain changes that have not yet been published to npm.

License

MIT