mcp-gh-issue-mini

A production-ready MCP (Model Context Protocol) server for managing GitHub Issues with robust authentication and modular architecture.

Easily create, search, update, comment on, and close issues in any repository—directly from MCP-compatible clients like Claude Code.

✨ Features

Core Functionality

• Create new issues in any GitHub repository
• List open issues with filtering
• Get detailed issue information
• Search issues with full GitHub query syntax (is:open label:bug "error")
• Update issues (title, body, state)
• Add comments with automatic MCP traceability
• Retrieve all issue comments
• Close issues

Advanced Features

• 🔐 Dual Authentication: PAT + GitHub CLI fallback
• 🏗️ Modular Architecture: Clean separation of concerns
• 📝 Comprehensive Logging: 4-level debug system
• ✅ Full Test Coverage: 68.64% with 29 passing tests
• 🚀 Zero Config: Works with npx instantly

🛠️ Quick Start

Instant Setup (Recommended)

# Works immediately with GitHub CLI auth
gh auth login
npx mcp-gh-issue-mini

VS Code MCP Configuration

{
  "mcp": {
    "servers": {
      "mcp-gh-issue-mini": {
        "command": "npx",
        "args": ["mcp-gh-issue-mini"],
        "env": {
          "GITHUB_PERSONAL_ACCESS_TOKEN": "${env:GITHUB_PERSONAL_ACCESS_TOKEN}"
        }
      }
    }
  }
}

Optional: Add "DEBUG_MCP_GH_ISSUE": "true" to env for detailed logging

🔐 Authentication System

Recommended: GitHub CLI Authentication

gh auth login  # One-time setup
npx mcp-gh-issue-mini  # Works immediately

Alternative: Personal Access Token

Set the environment variable GITHUB_PERSONAL_ACCESS_TOKEN if you prefer PAT authentication.

Required PAT Permissions: | Permission | Access Level | |------------|--------------| | Issues | Read & Write | | Metadata | Read (automatic) |

Debug Mode

DEBUG_MCP_GH_ISSUE=true npx mcp-gh-issue-mini

📋 Available Tools

1. create_issue - Create new GitHub issue
2. list_open_issues - List repository's open issues
3. get_issue - Get detailed issue information
4. update_issue - Update issue title, body, or state
5. close_issue - Close an issue
6. search_issues - Search issues with GitHub query syntax
7. add_issue_comment - Add comment to issue
8. get_issue_comments - Retrieve all issue comments

🏗️ Architecture

Modular Design

src/
├── api/           # GitHub API integration
├── auth/          # Dual authentication system  
├── utils/         # Logging & helper functions
├── test/          # Comprehensive test suite
└── index.ts       # MCP server entry point

Key Components

• Unified GitHub API Client: Consolidated API handling
• Smart Authentication: Automatic PAT → CLI fallback
• Configurable Logging: ERROR/WARN/INFO/DEBUG levels
• Complete Type Safety: Full TypeScript definitions

📊 Quality Metrics

• ✅ 29 tests passing (0 failures)
• ✅ 68.64% code coverage
• ✅ 0 security vulnerabilities
• ✅ <5s build time
• ✅ 8.6 kB package size

🚀 Installation & Distribution

NPM Package

# Direct usage
npx mcp-gh-issue-mini

# Install globally  
npm install -g mcp-gh-issue-mini

Development Setup

git clone https://github.com/y-hirakaw/mcp-gh-issue-mini.git
cd mcp-gh-issue-mini
npm install
npm run build
npm test

💡 Why This Server?

Production-Ready: Robust error handling, comprehensive logging, dual authentication Developer-Friendly: Full TypeScript, extensive testing, clear architecture
Zero Dependencies: Minimal footprint with only essential dependencies Real-World Tested: Verified with actual GitHub repositories and various authentication scenarios

Perfect for learning MCP development patterns or integrating GitHub Issues into AI workflows.

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Bug reports, suggestions, and PRs welcome! This project follows standard open-source contribution practices.