GitHub Issue Relationships MCP Server

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: ``bash 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