GitHub Issue MCP

npm install github-issue-mcp
The package is available on npm as:
github-issue-mcp
Current release:
v1.1.2🚀 Quick StartRun 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_tokenGITHUB_OWNER=your_github_usernameGITHUB_REPO=your_repository

GEMINI_API_KEY=your_gemini_api_key

GEMINI_MODEL=gemini-3.6-flashGEMINI_MAX_RETRIES=3GEMINI_RETRY_BASE_DELAY=1000

DEBUG=falseEnvironment variablesVariable	Required	Description	DefaultGITHUB_TOKEN	Yes	GitHub API authentication token	RequiredGITHUB_OWNER	Yes	GitHub repository owner or organization	RequiredGITHUB_REPO	Yes	GitHub repository name	RequiredGEMINI_API_KEY	Yes	Google Gemini API key	RequiredGEMINI_MODEL	No	Gemini model used by the AI client	gemini-3.6-flashGEMINI_MAX_RETRIES	No	Maximum number of Gemini retries	3GEMINI_RETRY_BASE_DELAY	No	Base retry delay in milliseconds	1000DEBUG	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	Purposegenerate_issue	Generate a structured GitHub issuecreate_github_issue	Create an issue on GitHublist_github_issues	Retrieve open repository issueslist_github_labels	Retrieve repository labelscheck_duplicate_issue	Find likely duplicate issue candidatesgenerate_issue
Generates a structured issue from supplied information.
InputsdescriptionreproductionStepsexpectedBehavioractualBehaviorenvironmentadditionalContextExample 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 1Duplicate Detection        │        ▼Semantic Analysis        │        ▼Phase 2Collect Details        │        ▼Phase 3Issue Generation        │        ▼Phase 4Human Approval        │        ▼Phase 5GitHub 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 crasheswhen 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:
loginpagebuttoncrashissue🤖 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_issuecreate_github_issue
during this phase.
Phase 3 — Issue Generation
Gemini receives:
list_github_labelsgenerate_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_issueGenerate Phase      │      ├── list_github_labels      └── generate_issueCreation Phase      │      └── create_github_issue             (client-controlled)2. 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.
3. 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 Issue   │   ▼CLI Displays Issue   │   ▼User Approval   │   ├── No ──► Stop   │   └── Yes         │         ▼Client invokes create_github_issue         │         ▼GitHub
Creating a GitHub issue is a persistent external side effect.
Therefore, the AI proposes the action while the user controls the final write operation.
🔄 Gemini Error Handling
The Gemini client includes retry handling for temporary API failures.
HTTP 429
The system distinguishes between temporary rate-limit errors and exhausted daily quotas.
Temporary 429 errors are retried according to the configured retry policy.
Daily quota exhaustion is detected separately and is not repeatedly retried because additional requests cannot succeed until the quota resets or a different Gemini project/model is used.
HTTP 5xx
Temporary Gemini server-side failures are retried automatically.
Examples include:
500502503504Retry Configuration
Retry behavior can be configured through environment variables:
GEMINI_MAX_RETRIES=3GEMINI_RETRY_BASE_DELAY=1000
The retry delay increases between attempts.
Invalid JSON
If an MCP tool expected to return JSON produces malformed output, the agent reports a clear error.
Examples:
generate_issue returned invalid JSON.
or:
check_duplicate_issue returned invalid JSON.
This keeps failures localized and easier to diagnose.
📚 Use as a Library
GitHub Issue MCP is designed to be embedded into another Node.js application.
Create an MCP serverimport {  createGitHubIssueMcpServer} from "github-issue-mcp/server";

const server = createGitHubIssueMcpServer({  name: "my-github-issue-server",  version: "1.0.0"});
The server factory has no dependency on a specific transport, allowing the MCP server to be reused by different hosts and transports.
Start a stdio serverimport {  startStdioServer} from "github-issue-mcp/server/stdio";

await startStdioServer();Start the executable CLInpx -y github-issue-mcp
The executable starts the reusable MCP server using the stdio transport.
📦 Package Exports
The npm package exposes the following public entry points:
github-issue-mcpgithub-issue-mcp/servergithub-issue-mcp/server/stdioServer factoryimport {  createGitHubIssueMcpServer} from "github-issue-mcp/server";Stdio serverimport {  startStdioServer} from "github-issue-mcp/server/stdio";CLInpx -y github-issue-mcp🌐 MCP Registry
GitHub Issue MCP is published to the official MCP Registry.
Registry identifier:
io.github.sarim-aliii/github-issue-mcp
npm package:
github-issue-mcp
Current release:
v1.1.2
The Registry publication allows MCP-compatible ecosystems to discover the server using its official registry identity.
🧪 Testing
The project uses Vitest for automated testing.
The current test suite contains:
12 test files47 tests47 passing
Tests cover multiple layers of the application.
GitHub API Teststests/github/issues.test.ts
Validates:
GitHub issue retrievalPull-request filteringLabel retrievalLabel validationEmpty label handlingGitHub issue creationGitHub API error handlingMCP Tool Teststests/tools/mcp-tools.test.ts
Validates:
MCP tool registrationMCP tool invocationTool argument handlingMCP error responsesIssue Generation Teststests/tools/generate-issue.test.ts
Validates:
Bug issue generationOptional field handlingFallback placeholdersStructured issue outputDuplicate Detection Teststests/tools/check-duplicate.test.ts
Validates:
Candidate retrievalSimilarity rankingCandidate limitingDuplicate detection behaviorGemini Agent Teststests/client/agent.test.ts
Validates:
Gemini request handlingTemporary 429 retry behaviorTemporary 5xx retry behaviorDaily quota handlingMaximum retry behaviorNon-retryable errorsAgent Workflow Teststests/client/agent-workflow.test.ts
Validates:
Duplicate-check phase restrictionsIssue-generation phase restrictionsLabel lookupStructured issue generationAutonomous creation protectionMalformed MCP responsesWorkflow Teststests/client/workflow.test.ts
Validates:
Duplicate workflow terminationSuccessful issue generation and creationApproval rejectionMissing generated issue handlingConfiguration Teststests/client/config.test.ts
Validates:
Default Gemini configurationEnvironment-variable configurationMCP Integration Teststests/integration/mcp-server.test.ts
Validates:
MCP server startupMCP connection behaviorMCP tool availabilityPackage API Integration Teststests/integration/package-api.test.ts
Validates the public npm package API and ensures the published package exposes the expected reusable server interfaces.
Issue Creation Safety Tests
The integration suite also validates that the issue creation boundary remains client-controlled and that the autonomous agent cannot bypass the intended approval flow.
▶️ Run Tests
Run the complete test suite:
npm test
Run TypeScript validation:
npm run typecheck
Build the project:
npm run build
Expected current result:
Test Files  12 passed (12)Tests       47 passed (47)📊 Test Coverage
The current suite validates:
✓ GitHub API interactions✓ Issue listing✓ Pull-request filtering✓ Label retrieval✓ Label validation✓ Issue creation✓ GitHub API error handling✓ MCP tool registration✓ MCP tool invocation✓ Issue generation✓ Duplicate candidate retrieval✓ Lexical candidate ranking✓ Semantic duplicate workflow✓ Gemini retries✓ Gemini 429 handling✓ Gemini 5xx handling✓ Gemini quota handling✓ Malformed JSON handling✓ Agent phase restrictions✓ Human-controlled write boundary✓ Workflow orchestration✓ Approval handling✓ MCP integration✓ Package API✓ Configuration defaults✓ Environment-based configuration🧪 Consumer Integration Testing
The project also validates installation from the built npm package in a clean consumer project.
The tested flow is:
Build package      │      ▼npm pack      │      ▼Install package in clean project      │      ▼Import public API      │      ▼Create MCP server      │      ▼Start stdio server      │      ▼Connect with MCP Client      │      ▼Discover tools
The published package has been tested using:
npm install github-issue-mcp
and the executable:
npx github-issue-mcp
The consumer integration verifies that the expected MCP tools are available.
🛠️ Tech StackLanguageTypeScriptNode.jsAIGoogle Gemini@google/genaiMCP@modelcontextprotocol/sdkValidationZodCLIInquirerTestingVitestGitHubGitHub REST API📁 Project Structuregithub-issue-mcp/│   │   ├── agent.ts│   │   ├── ai-client.ts│   │   ├── approval.ts│   │   ├── cli.ts│   │   ├── config.ts│   │   ├── index.ts│   │   ├── issue-details.ts│   │   ├── logger.ts│   │   ├── tool-adapter.ts│   │   └── workflow.ts│   ││   ├── github/│   │   ├── client.ts│   │   └── issues.ts│   ││   ├── server/│   │   ├── cli.ts│   │   ├── create-server.ts│   │   ├── index.ts│   │   └── stdio.ts│   ││   ├── tools/│   │   ├── check-duplicate.ts│   │   ├── create-issue.ts│   │   ├── generate-issue.ts│   │   ├── list-issues.ts│   │   └── list-labels.ts│   ││   ├── types/│   │   └── issue.ts│   ││   └── index.ts│├── examples/│   ├── basic-server/│   │   └── index.mjs│   ││   ├── stdio-client/│   │   └── index.mjs│   ││   └── README.md│├── tests/│   ├── client/│   │   ├── agent.test.ts│   │   ├── agent-workflow.test.ts│   │   ├── config.test.ts│   │   └── workflow.test.ts│   ││   ├── github/│   │   └── issues.test.ts│   ││   ├── integration/│   │   ├── issue-creation-safety.test.ts│   │   ├── mcp-server.test.ts│   │   └── package-api.test.ts│   ││   ├── server/│   │   └── create-server.test.ts│   ││   └── tools/│       ├── check-duplicate.test.ts│       ├── generate-issue.test.ts│       └── mcp-tools.test.ts│├── .env.example├── .gitignore├── package.json├── server.json├── tsconfig.json└── README.md⚙️ Local Development Setup1. Clone the repositorygit clone https://github.com/sarim-aliii/github-issue-mcp.gitcd github-issue-mcp2. Install dependenciesnpm install3. Configure environment variables
Create a .env file:
GITHUB_TOKEN=your_github_tokenGITHUB_OWNER=your_github_usernameGITHUB_REPO=your_repository

GEMINI_API_KEY=your_gemini_api_key

GEMINI_MODEL=gemini-3.6-flashGEMINI_MAX_RETRIES=3GEMINI_RETRY_BASE_DELAY=1000

DEBUG=false
Never commit .env to Git.
▶️ Running the Assistant
The original interactive client can be started with:
npx tsx src/client/index.ts
The assistant will ask for a short issue description.
Example:
✔ Describe your issue:The export button on the reports page does nothing when clicked.
The assistant will then:
1. Connect to the MCP server2. Discover available MCP tools3. Search for possible duplicates4. Analyze candidates semantically5. Stop if a duplicate exists6. Ask for additional details7. Generate a structured issue8. Display the proposed issue9. Ask for human confirmation10. Create the issue if approved💡 ExampleInputThe export button on the reports page does nothing when clicked.Additional InformationReproductionOpen the reports page, select a report, and click Export.ExpectedThe selected report should be downloaded as a CSV file.ActualNothing happens after clicking Export.EnvironmentChrome 126, Windows 11, App v2.4.1.Additional contextThe issue occurs consistently.Generated Issue## Description

The export button on the reports page does nothing when clicked.

## Steps to Reproduce

Open the reports page, select a report, and click Export.

## Expected Behavior

The selected report should be downloaded as a CSV file.

## Actual Behavior

Nothing happens after clicking the Export button.

## Environment

Chrome 126, Windows 11, App v2.4.1.

## Additional Context

The issue occurs consistently.
The user then sees:
Create this issue on GitHub? [y/N]:
Only an explicit approval creates the issue.
🧠 Design DecisionsWhy MCP?
MCP provides a standardized interface between the AI agent and external capabilities.
Instead of embedding GitHub API logic directly into the Gemini workflow, GitHub operations are exposed as MCP tools.
                 Gemini                    │                    │ MCP                    ▼              GitHub Tools                    │                    ▼             GitHub REST API
This keeps the AI layer separated from external-service logic and makes the tools reusable.
Why separate duplicate retrieval and semantic analysis?
The candidate retrieval process is inexpensive and deterministic enough to narrow the search space.
Gemini then performs the more expensive semantic reasoning only on relevant candidates.
All Open Issues      │      ▼Lexical Candidate Ranking      │      ▼Small Candidate Set      │      ▼Gemini Semantic Analysis      │      ▼Duplicate / Not Duplicate
This is more efficient than asking an LLM to reason over every issue in a repository.
Why require human approval?
Creating a GitHub issue is a persistent external side effect.
The system therefore separates:
AI Reasoning
from:
External Write Operation
The AI proposes the issue while the user controls the final action.
Why restrict tools by phase?
Different workflow stages require different capabilities.
Giving the model access to every tool at every stage increases the possibility of unintended behavior.
Instead:
Duplicate Phase       │       ▼check_duplicate_issueGenerate Phase       │       ├── list_github_labels       └── generate_issueCreation Phase       │       ▼create_github_issue(client controlled)
This makes the agent's permissions explicit and easier to reason about.
🛡️ Reliability
The project includes explicit handling for temporary Gemini failures.
Temporary 429     │     ▼Retry according to policyTemporary 5xx     │     ▼Retry according to policyDaily quota exhausted     │     ▼Stop immediately
This avoids wasting retry attempts when a daily quota cannot be recovered through another request.
🚧 Future Improvements
Potential future improvements include:
More sophisticated duplicate-ranking algorithmsGitHub issue commentsIssue updatesIssue assignmentMilestone supportGitHub Projects integrationPull-request creationAutomatic issue categorizationRepository-specific issue templatesSupport for multiple GitHub repositoriesPersistent conversation contextStreaming Gemini responsesMore comprehensive end-to-end integration testsStructured logging and observabilityMetrics for agent/tool executionRepository-specific issue policiesAdditional MCP transports🎯 Project Goals
This project demonstrates how to combine:
LLM Reasoning      +MCP Tool Calling      +External APIs      +Structured Validation      +Semantic Duplicate Detection      +Human Approval      +Automated Testing
The main goal is not simply to generate GitHub issues with AI.
The goal is to demonstrate a controlled agentic workflow where:
The model can reasonThe model can use toolsTool access is restricted by workflow phaseGitHub operations are isolated behind MCPDuplicate detection combines deterministic retrieval with AI reasoningPersistent writes require explicit human approvalTemporary AI failures are handled automaticallyThe MCP server can be reused independently of the interactive clientThe package can be consumed by other Node.js applicationsThe package can be launched directly as an MCP stdio serverThe workflow is covered by automated tests📌 Current StatusProjectFunctionalPackagegithub-issue-mcpv1.1.2MCP Registryio.github.sarim-aliii/github-issue-mcpTypeScript✓ Typecheck passing✓ Build passingTests✓ 12 test files✓ 47 tests✓ 47 passingCore Workflow✓ MCP server✓ MCP client✓ Gemini integration✓ Duplicate candidate retrieval✓ Semantic duplicate analysis✓ Issue generation✓ Label retrieval✓ Human approval✓ GitHub issue creationReusable Package✓ npm package✓ Public server factory✓ Public stdio server API✓ Executable MCP CLI✓ Consumer integration test✓ Package API integration testSafety✓ Phase-restricted Gemini tools✓ Autonomous write protection✓ Client-controlled GitHub creation✓ Human approval boundaryReliability✓ Gemini 429 retry handling✓ Gemini 5xx retry handling✓ Daily quota detection✓ Configurable retry policy✓ Invalid JSON handling📄 License
This project is intended as a demonstration and reusable implementation of an AI-powered, MCP-based GitHub issue management workflow.
See the repository license for licensing terms.
🔗 Links
Repository:
https://github.com/sarim-aliii/github-issue-mcp
npm:
https://www.npmjs.com/package/github-issue-mcp
MCP Registry:
https://registry.modelcontextprotocol.io/