GitHub Issue Relationships MCP Server

An MCP (Model Context Protocol) server that provides tools for managing GitHub issue relationships - tracking dependencies, blockers, and sub-issues.

Features

Issue Dependencies

• github_get_blocked_by - List issues blocking a specific issue
• github_get_blocking - List issues that an issue is blocking
• github_add_blocking_dependency - Add a blocking dependency
• github_remove_blocking_dependency - Remove a blocking dependency

Sub-Issues

• github_get_parent_issue - Get the parent of a sub-issue
• github_list_sub_issues - List all sub-issues of a parent
• github_add_sub_issue - Add a sub-issue to a parent
• github_remove_sub_issue - Remove a sub-issue
• github_reprioritize_sub_issue - Change sub-issue priority order

Setup

Prerequisites

• Node.js 20+
• GitHub CLI (gh) authenticated, OR a GitHub Personal Access Token

Installation

# Clone the repository
git clone <repo-url>
cd git-relationship-mcp

# Install dependencies
npm install

# Build (optional, for production)
npm run build

Authentication

The server requires a GitHub token with repo scope. You have two options:

Option 1: Use GitHub CLI (Recommended)

If you're authenticated with gh, the Claude Desktop config can retrieve the token automatically.

Option 2: Environment Variable

Set GITHUB_TOKEN directly:

export GITHUB_TOKEN=ghp_your_token_here

Claude Desktop Configuration

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Using GitHub CLI authentication (Windows):

{
  "mcpServers": {
    "github-issues": {
      "command": "cmd",
      "args": ["/c", "for /f %i in ('gh auth token') do @set GITHUB_TOKEN=%i && npx tsx src/index.ts"],
      "cwd": "C:\\path\\to\\git-relationship-mcp"
    }
  }
}

Using direct token:

{
  "mcpServers": {
    "github-issues": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"],
      "cwd": "C:\\path\\to\\git-relationship-mcp",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Development

# Run in development mode
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

Verifying Installation

After configuring Claude Desktop, test the server by asking Claude:

"List the tools from the github-issues server"

Claude should respond with 9 tools (github_get_blocked_by, github_get_blocking, github_add_blocking_dependency, etc.).

Manual Verification

Test the server starts correctly:

# Using GitHub CLI
GITHUB_TOKEN=$(gh auth token) npx tsx src/index.ts

# Using direct token
GITHUB_TOKEN=ghp_your_token npx tsx src/index.ts

The server should output startup information. Press Ctrl+C to exit.

Troubleshooting

Issue	Cause	Solution
"GITHUB_TOKEN environment variable is required"	Token not set or gh not authenticated	Run gh auth login or set GITHUB_TOKEN directly
"Repository not found" (404)	Token lacks repo scope or repo doesn't exist	Ensure token has repo scope; verify owner/repo spelling
"Rate limit exceeded" (403)	GitHub API limit hit	Wait 1 hour or use a PAT with higher limits
Server doesn't appear in Claude Desktop	Config file syntax error	Validate JSON syntax; check file location
"Permission denied" on write operations	Token lacks write permissions	Regenerate token with repo scope
"Issue not found" for existing issue	Using issue number instead of ID for write ops	Use issue ID (from API or URL) for *_id parameters

Example Usage

Once configured in Claude Desktop, you can ask Claude:

• "What issues are blocking issue #42 in owner/repo?"
• "List the sub-issues of issue #10 in my-org/project"
• "Add issue #5 as a sub-issue of #1 in my-repo"
• "Show me what issues #15 is blocking"

API Reference

See GitHub Issue Dependencies API and GitHub Sub-Issues API for full API documentation.

License

MIT