GitHub Issue MCP

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
• 🔌 Published npm package
• 🚀 Executable github-issue-mcp MCP CLI
• 🌐 Published to the official MCP Registry
• 🛡️ Phase-restricted AI tool access
• 🔗 Separation between AI reasoning and external GitHub operations

---

📦 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

GEMINI_MODEL=gemini-3.6-flash GEMINI_MAX_RETRIES=3 GEMINI_RETRY_BASE_DELAY=1000

DEBUG=false Environment variables Variable Required Description Default GITHUB_TOKEN Yes GitHub API authentication token Required GITHUB_OWNER Yes GitHub repository owner or organization Required GITHUB_REPO Yes GitHub repository name Required GEMINI_API_KEY Yes Google Gemini API key Required GEMINI_MODEL No Gemini model used by the AI client gemini-3.6-flash GEMINI_MAX_RETRIES No Maximum number of Gemini retries 3 GEMINI_RETRY_BASE_DELAY No Base retry delay in milliseconds 1000 DEBUG No Enables debug behavior/logging false

Never commit .env, GitHub tokens, or Gemini API keys to Git.

🧩 MCP Tools

The MCP server exposes the following tools:

Tool Purpose generate_issue Generate a structured GitHub issue create_github_issue Create an issue on GitHub list_github_issues Retrieve open repository issues list_github_labels Retrieve repository labels check_duplicate_issue Find likely duplicate issue candidates generate_issue

Generates a structured issue from supplied information.

Inputs description reproductionSteps expectedBehavior actualBehavior environment additionalContext Example output { "title": "Bug: Login button does not work", "body": "## Description\n\nLogin button does not work...", "labels": ["bug"] } check_duplicate_issue

Retrieves likely duplicate candidates from the repository.

The tool performs inexpensive lexical candidate ranking against existing open issues.

The similarity score is not treated as proof of duplication.

Gemini performs the final semantic analysis.

This keeps the expensive AI reasoning focused on a small candidate set rather than every issue in the repository.

list_github_issues

Retrieves open GitHub issues while filtering out pull requests.

list_github_labels

Retrieves labels available in the repository.

create_github_issue

Creates the final GitHub issue.

This tool is intentionally not exposed to the autonomous Gemini agent.

It is invoked directly by the client only after explicit human approval.

🏗️ Architecture ┌──────────────────┐ │ User │ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ CLI Client │ └────────┬─────────┘ │ ▼ ┌──────────────────────────┐ │ MCP Client │ └────────────┬─────────────┘ │ ▼ ┌──────────────────────────┐ │ MCP Server │ └────────────┬─────────────┘ │ ┌──────────────────┼──────────────────┐ │ │ │ ▼ ▼ ▼ Duplicate Check Issue Generation GitHub Tools │ │ │ ▼ ▼ ▼ Candidate Issues Proposed Issue GitHub REST API │ │ ▼ ▼ Gemini Semantic Human Approval Analysis │ │ │ ┌────┴────┐ ┌────┴────┐ │ │ │ │ Yes No No Yes │ │ │ │ ▼ ▼ ▼ ▼ Stop Continue Stop Create Issue 🔑 Core Design Principle

The most important architectural decision is:

Gemini does not have autonomous access to the GitHub write operation.

The workflow is intentionally divided into controlled phases.

Phase 1 Duplicate Detection │ ▼ Semantic Analysis │ ▼ Phase 2 Collect Details │ ▼ Phase 3 Issue Generation │ ▼ Phase 4 Human Approval │ ▼ Phase 5 GitHub Creation

This provides a clear human-in-the-loop safety boundary around persistent external side effects.

🔄 Workflow

The complete workflow is:

1. User describes an issue │ ▼
2. Retrieve duplicate candidates │ ▼
3. Gemini performs semantic analysis │ ┌──────┴──────┐ │ │ Duplicate No duplicate │ │ ▼ ▼ Stop 4. Collect additional details │ ▼
4. Gemini generates structured issue │ ▼
5. Display proposed issue │ ▼
6. Ask user for approval │ ┌──────┴──────┐ │ │ No Yes │ │ ▼ ▼ Stop 8. Client creates GitHub issue

🔍 Duplicate Detection

Duplicate detection is deliberately split into two stages.

Stage 1 — Candidate Retrieval

The MCP tool performs inexpensive lexical similarity/ranking against existing open issues.

For example:

User:

"The search results page crashes when I apply multiple filters."

│ ▼

check_duplicate_issue

│ ▼

Candidate #8

"The search results page crashes when I apply multiple filters."

Similarity: 0.21

The similarity score is only used to identify potentially relevant candidates.

It is not considered proof of duplication.

Stage 2 — Semantic Analysis

Gemini receives the candidate issues and determines whether any candidate describes the same underlying problem.

Example:

{ "isDuplicate": true, "duplicateIssue": { "number": 8, "title": "Bug: The search results page crashes when I apply multiple filters.", "url": "https://github.com/example/repository/issues/8" }, "reason": "The candidate describes the exact same underlying problem." }

This prevents unrelated issues from being incorrectly classified as duplicates merely because they share common words such as:

login page button crash issue 🤖 Agent Workflow

The Gemini agent supports controlled multi-step tool execution.

Available MCP tools are restricted according to the current workflow phase.

Phase 1 — Duplicate Detection

Gemini receives:

check_duplicate_issue

The agent can use this tool to retrieve candidate issues.

It cannot use:

generate_issue create_github_issue

during this phase.

Phase 3 — Issue Generation

Gemini receives:

list_github_labels generate_issue

This allows the agent to inspect repository labels and generate the proposed issue.

It still cannot create the GitHub issue.

Phase 5 — Issue Creation

The autonomous Gemini agent does not receive:

create_github_issue

Instead, the application directly invokes the tool after explicit human approval.

🔐 Security Model

The project uses multiple layers to prevent unintended GitHub writes.

1. Phase-Based Tool Exposure

Available tools are restricted depending on the current workflow phase.

Duplicate Phase │ └── check_duplicate_issue Generate Phase │ ├── list_github_labels └── generate_issue Creation Phase │ └── create_github_issue (client-controlled)

1. Autonomous Write Protection

The Gemini agent cannot directly invoke:

create_github_issue

Even if the model attempts to request the tool, the agent workflow rejects the operation.

1. Human Approval

The proposed issue is displayed to the user before creation.

Example:

================================ PROPOSED GITHUB ISSUE ================================

Title: Bug: Login button does not work with valid credentials.

Labels: bug

Body:

Description

Login button does not work with valid credentials.

Steps to Reproduce

Open login page → enter valid credentials → click Login.

Expected Behavior

User should be redirected to the dashboard.

Actual Behavior

Nothing happens after clicking Login.

Create this issue on GitHub? [y/N]:

Only explicit approval proceeds to the GitHub write operation.

👤 Human-in-the-Loop Creation

Issue creation is intentionally controlled by the application.

Gemini │ ▼ Generate Proposed Iss