y-hirakaw/mcp-gh-issue-mini
If you are the rightful owner of mcp-gh-issue-mini and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
A minimal MCP server for interacting with GitHub Issues.
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
npxinstantly
🛠️ 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
create_issue- Create new GitHub issuelist_open_issues- List repository's open issuesget_issue- Get detailed issue informationupdate_issue- Update issue title, body, or stateclose_issue- Close an issuesearch_issues- Search issues with GitHub query syntaxadd_issue_comment- Add comment to issueget_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.
