Converts natural-language bug reports into structured GitHub issues while using semantic analysis to detect existing duplicates.
Also known as sarim-aliii/github-issue-mcp, github-issue-mcp
- Stars
- 0
- Tools
- โ
- Downloads, 30 days
- โ
- Latest version
- 1.1.2
- Last commit
- Oct 22, 2026
- License
- โ
What is GitHub Issue MCP Assistant MCP?
GitHub Issue MCP Assistant converts natural-language bug reports into structured GitHub issues while using semantic analysis to detect existing duplicates.
Summary generated from the project's README
About GitHub Issue MCP Assistant MCP server
Converting natural language bug reports into structured GitHub issues is the primary function of this MCP server. It is designed for developers and maintainers who want to automate issue management without losing control over their repository. The system uses Google Gemini to perform semantic analysis, which allows it to distinguish between true duplicates and issues that merely share common keywords like login or crash.
Users interact with the server via an MCP-compatible client using stdio. To function, the setup requires a GitHub personal access token, a GitHub repository owner, a repository name, and a Gemini API key. The server is available as an npm package that can be run using npx or embedded into other Node.js applications.
A key safety feature is the separation of AI reasoning from GitHub write operations. While Gemini can use tools like generate_issue and check_duplicate_issue to analyze data, it is intentionally restricted from using the create_github_issue tool. This ensures that a human must review and approve the final structured issue before any changes are made to the GitHub repository.
What you can do with it
- 1Detecting duplicate bug reportsAn AI client can check if a new bug report describes a problem that has already been submitted to the repository.
- 2Structuring messy bug descriptionsA developer can provide a brief description of a problem and have the AI generate a formal issue with reproduction steps and expected behavior.
- 3Validating repository labelsThe system can retrieve and validate existing labels to ensure new issues are categorized correctly.
- 4Preventing unauthorized repository writesMaintainers can use the server to ensure that an autonomous agent never creates an issue without explicit human consent.
Written from the project's README. Every use case is checked against a quote from it.
How to install GitHub Issue MCP Assistant MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall GitHub Issue MCP Assistant MCP in Claude Code
$ claude mcp add --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' --env 'GITHUB_OWNER=<GITHUB_OWNER>' --env 'GITHUB_REPO=<GITHUB_REPO>' github-issue-mcp -- npx -y github-issue-mcpInstall GitHub Issue MCP Assistant MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"github-issue-mcp": {
"command": "npx",
"args": [
"-y",
"github-issue-mcp"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"GITHUB_OWNER": "<GITHUB_OWNER>",
"GITHUB_REPO": "<GITHUB_REPO>"
}
}
}
}Install GitHub Issue MCP Assistant MCP in VS Code
.vscode/mcp.json
{
"servers": {
"github-issue-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"github-issue-mcp"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"GITHUB_OWNER": "<GITHUB_OWNER>",
"GITHUB_REPO": "<GITHUB_REPO>"
}
}
}
}Install GitHub Issue MCP Assistant MCP in VS Code CLI
$ code --add-mcp '{"name":"github-issue-mcp","type":"stdio","command":"npx","args":["-y","github-issue-mcp"],"env":{"GEMINI_API_KEY":"<YOUR_GEMINI_API_KEY>","GITHUB_TOKEN":"<YOUR_GITHUB_TOKEN>","GITHUB_OWNER":"<GITHUB_OWNER>","GITHUB_REPO":"<GITHUB_REPO>"}}'Install GitHub Issue MCP Assistant MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"github-issue-mcp": {
"command": "npx",
"args": [
"-y",
"github-issue-mcp"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"GITHUB_OWNER": "<GITHUB_OWNER>",
"GITHUB_REPO": "<GITHUB_REPO>"
}
}
}
}Install GitHub Issue MCP Assistant MCP in Codex
$ codex mcp add github-issue-mcp --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' --env 'GITHUB_OWNER=<GITHUB_OWNER>' --env 'GITHUB_REPO=<GITHUB_REPO>' -- npx -y github-issue-mcpInstall GitHub Issue MCP Assistant MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.github-issue-mcp] command = "npx" args = ["-y", "github-issue-mcp"] [mcp_servers.github-issue-mcp.env] GEMINI_API_KEY = "<YOUR_GEMINI_API_KEY>" GITHUB_TOKEN = "<YOUR_GITHUB_TOKEN>" GITHUB_OWNER = "<GITHUB_OWNER>" GITHUB_REPO = "<GITHUB_REPO>"
Install GitHub Issue MCP Assistant MCP in Gemini CLI
$ gemini mcp add -s user -e 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' -e 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' -e 'GITHUB_OWNER=<GITHUB_OWNER>' -e 'GITHUB_REPO=<GITHUB_REPO>' github-issue-mcp npx -- -y github-issue-mcpInstall GitHub Issue MCP Assistant MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"github-issue-mcp": {
"command": "npx",
"args": [
"-y",
"github-issue-mcp"
],
"env": {
"GEMINI_API_KEY": "<YOUR_GEMINI_API_KEY>",
"GITHUB_TOKEN": "<YOUR_GITHUB_TOKEN>",
"GITHUB_OWNER": "<GITHUB_OWNER>",
"GITHUB_REPO": "<GITHUB_REPO>"
}
}
}
}Configuration
GEMINI_API_KEYRequiredSecretGoogle Gemini API key used for AI-powered issue generation and semantic duplicate analysis.
GITHUB_TOKENRequiredSecretGitHub personal access token used to access the configured repository.
GITHUB_OWNERRequiredGitHub repository owner or organization.
GITHUB_REPORequiredGitHub repository name.
GEMINI_MAX_RETRIESGEMINI_MODELGEMINI_RETRY_BASE_DELAY
Automated checks
Ran Nov 14, 2026Full report โPassed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work ยท What to fix for more points
- Source repository linked and reachablesarim-aliii/github-issue-mcp is public and reachablegithub.com/sarim-aliii/github-issue-mcp โPass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-22github.com/sarim-aliii/github-issue-mcp โPass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from github-issue-mcpPass
- No critical advisory in the package or its dependencies162 resolved dependencies checked; no critical advisoryosv.dev โPass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubGitHub 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-mcpMCP 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
โ
โผ
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
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)
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:
500
502
503
504
Retry Configuration
Retry behavior can be configured through environment variables:
GEMINI_MAX_RETRIES=3
GEMINI_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 server
import {
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 server
import {
startStdioServer
} from "github-issue-mcp/server/stdio";
await startStdioServer();
Start the executable CLI
npx -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-mcp
github-issue-mcp/server
github-issue-mcp/server/stdio
Server factory
import {
createGitHubIssueMcpServer
} from "github-issue-mcp/server";
Stdio server
import {
startStdioServer
} from "github-issue-mcp/server/stdio";
CLI
npx -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 files
47 tests
47 passing
Tests cover multiple layers of the application.
GitHub API Tests
tests/github/issues.test.ts
Validates:
GitHub issue retrieval
Pull-request filtering
Label retrieval
Label validation
Empty label handling
GitHub issue creation
GitHub API error handling
MCP Tool Tests
tests/tools/mcp-tools.test.ts
Validates:
MCP tool registration
MCP tool invocation
Tool argument handling
MCP error responses
Issue Generation Tests
tests/tools/generate-issue.test.ts
Validates:
Bug issue generation
Optional field handling
Fallback placeholders
Structured issue output
Duplicate Detection Tests
tests/tools/check-duplicate.test.ts
Validates:
Candidate retrieval
Similarity ranking
Candidate limiting
Duplicate detection behavior
Gemini Agent Tests
tests/client/agent.test.ts
Validates:
Gemini request handling
Temporary 429 retry behavior
Temporary 5xx retry behavior
Daily quota handling
Maximum retry behavior
Non-retryable errors
Agent Workflow Tests
tests/client/agent-workflow.test.ts
Validates:
Duplicate-check phase restrictions
Issue-generation phase restrictions
Label lookup
Structured issue generation
Autonomous creation protection
Malformed MCP responses
Workflow Tests
tests/client/workflow.test.ts
Validates:
Duplicate workflow termination
Successful issue generation and creation
Approval rejection
Missing generated issue handling
Configuration Tests
tests/client/config.test.ts
Validates:
Default Gemini configuration
Environment-variable configuration
MCP Integration Tests
tests/integration/mcp-server.test.ts
Validates:
MCP server startup
MCP connection behavior
MCP tool availability
Package API Integration Tests
tests/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 Stack
Language
TypeScript
Node.js
AI
Google Gemini
@google/genai
MCP
@modelcontextprotocol/sdk
Validation
Zod
CLI
Inquirer
Testing
Vitest
GitHub
GitHub REST API
๐ Project Structure
github-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 Setup
1. Clone the repository
git clone https://github.com/sarim-aliii/github-issue-mcp.git
cd github-issue-mcp
2. Install dependencies
npm install
3. Configure environment variables
Create a .env file:
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
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 server
2. Discover available MCP tools
3. Search for possible duplicates
4. Analyze candidates semantically
5. Stop if a duplicate exists
6. Ask for additional details
7. Generate a structured issue
8. Display the proposed issue
9. Ask for human confirmation
10. Create the issue if approved
๐ก Example
Input
The export button on the reports page does nothing when clicked.
Additional Information
Reproduction
Open the reports page, select a report, and click Export.
Expected
The selected report should be downloaded as a CSV file.
Actual
Nothing happens after clicking Export.
Environment
Chrome 126, Windows 11, App v2.4.1.
Additional context
The 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.
GitHub Issue MCP Assistant MCP questions
How do I add GitHub Issue MCP Assistant MCP to Claude Code?
Run claude mcp add --env 'GEMINI_API_KEY=<YOUR_GEMINI_API_KEY>' --env 'GITHUB_TOKEN=<YOUR_GITHUB_TOKEN>' --env 'GITHUB_OWNER=<GITHUB_OWNER>' --env 'GITHUB_REPO=<GITHUB_REPO>' github-issue-mcp -- npx -y github-issue-mcp in your terminal. Add --scope user to make it available in every project.
How do I add GitHub Issue MCP Assistant MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How does the server handle duplicate issues?
It uses a two-stage process: first, it performs lexical candidate ranking to find potential matches, then uses Gemini for semantic analysis to confirm if the issues are truly duplicates.