GitHub Issue MCP server

GitHub Issue MCP Assistant

An AI-powered GitHub issue management system built with Model Context Protocol (MCP), Google Gemini, TypeScript, and the GitHub REST API.

GitHub Issue MCP turns a short natural-language bug report into a structured GitHub issue while intelligently checking for existing duplicates before anything is created.

The project demonstrates a controlled agentic workflow where Gemini can reason and use MCP tools, while persistent GitHub write operations remain explicitly controlled by the application and the user.

The MCP server is also packaged as a reusable npm package so it can be embedded into other Node.js applications or launched directly as an MCP stdio server.

✨ Features

• 🤖 AI-powered issue generation using Google Gemini
• 🔍 Duplicate issue detection
• 🧠 Semantic duplicate analysis instead of relying only on keyword matching
• 📝 Interactive collection of additional issue details
• 🏷️ Repository label retrieval and validation
• 👤 Human approval before issue creation
• 🔐 Prevents the autonomous AI agent from directly creating GitHub issues
• 🔄 Automatic retry handling for temporary Gemini API failures
• 🚦 Daily Gemini quota detection without unnecessary retries
• ⚙️ Configurable Gemini model and retry behavior
• 🧪 Comprehensive unit, workflow, and integration tests
• 📦 Reusable MCP server architecture

📦 Installation

Install from npm

npm install github-issue-mcp

The package is available on npm as:

github-issue-mcp

Current release:

v1.1.2
🚀 Quick Start
Run as an MCP server

The package exposes an executable MCP server CLI.

npx -y github-issue-mcp

The server communicates using MCP over stdio.

This is the recommended approach when configuring the server in an MCP-compatible client.

🔌 MCP Client Configuration

GitHub Issue MCP can be used with any MCP-compatible client that supports stdio servers.

Using npx

The simplest configuration uses the published npm package:

{
  "mcpServers": {
    "github-issue-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github-issue-mcp"
      ],
      "env": {
        "GITHUB_TOKEN": "YOUR_GITHUB_TOKEN",
        "GITHUB_OWNER": "YOUR_GITHUB_OWNER",
        "GITHUB_REPO": "YOUR_GITHUB_REPO",
        "GEMINI_API_KEY": "YOUR_GEMINI_API_KEY"
      }
    }
  }
}

The MCP client starts:

npx -y github-issue-mcp

and communicates with the server over stdio.

⚙️ Configuration

Create a .env file when running the project locally.

GITHUB_TOKEN=your_github_token
GITHUB_OWNER=your_github_username
GITHUB_REPO=your_repository

GEMINI_API_KEY=your_gemini_api_key

Shortened. The full README is on GitHub.