github-issues-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 ```bash # 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): ```json { "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: ```json { "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 ```bash # 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: ```bash # 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](https://docs.github.com/en/rest/issues/issue-dependencies) and [GitHub Sub-Issues API](https://docs.github.com/en/rest/issues/sub-issues) for full API documentation. ## License MIT