GitHub Issue Priority MCP Server

MCP GitHub Issue Priority Server

A Model Context Protocol (MCP) server that enables AI assistants to manage GitHub issues with deterministic priority scoring and concurrency-safe selection.

Quick Start

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

Features

• Priority-Based Issue Selection: Deterministic scoring algorithm ensures consistent issue prioritization across sessions
• Concurrency-Safe Locking: File-based atomic locking prevents multiple AI sessions from selecting the same issue
• Guided Workflow: 8-phase workflow (selection → research → branch → implementation → testing → commit → pr → review) with transition validation
• Automatic Labeling: Creates and manages priority (P0-P3), type (bug, feature, chore, docs), and status labels
• Stale Lock Detection: Automatically detects and cleans up locks from dead processes
• Audit Logging: JSON Lines logging for all operations with 30-day retention

Installation

Prerequisites

• Node.js 20+ - Download
• GitHub CLI (recommended) - Install and run gh auth login
  • Or: a GitHub personal access token with repo scope

Install from npm (recommended)

npm install -g mcp-git-issue-priority

Install specific version

npm install -g mcp-git-issue-priority@1.0.0

Install from source

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

Troubleshooting

Configuration

GitHub Authentication

The server supports two authentication methods:

Recommended: GitHub CLI (automatic)

If you have GitHub CLI installed and authenticated, the server automatically retrieves your token:

# One-time setup
gh auth login

This is the recommended approach - no manual token management required.

Alternative: Environment Variable

Set GITHUB_TOKEN with a personal access token that has repo scope:

export GITHUB_TOKEN="ghp_your_personal_access_token"

Or configure it in your MCP settings (see below).

Claude Code Configuration

Add to ~/.claude.json (global) or .claude/settings.json (project):

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

Using a personal access token instead of GitHub CLI? Add the token to the config:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

Verify Installation

After restarting Claude Code:

1. Run /mcp to see available MCP servers
2. The github-issue-priority server should be listed with 13 tools
3. Try list_backlog on any repository to confirm it's working

Available Tools

`create_issue`

Create a new GitHub issue with mandatory priority and type labels.

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

`select_next_issue`

Select and lock the highest-priority issue from the backlog. Uses deterministic scoring to ensure consistent selection.

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

`list_backlog`

List all open issues in priority order without acquiring locks (read-only).

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

`advance_workflow`

Advance the workflow to the next phase for a locked issue.

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - p