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
                     │
                     ▼
             5. Gemini generates
                structured issue
                     │
                     ▼
             6. Display proposed issue
                     │
                     ▼
             7. 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