github-issue-finder logo

github-issue-finder

by Ayesha KhatunUpdated May 4, 2026

Searches and retrieves GitHub issues using queries for repositories, keywords, labels, states, and assignees. Returns issue details like title, body, and metadata. Developers and repository maintainers use it to automate issue tracking, triage bugs, and check for duplicates before filing new reports.

github
issues
search
|

Overview

The github-issue-finder MCP server connects AI models to GitHub's issue search API, enabling programmatic discovery of issues without direct authentication in client code. It processes search queries to list matching issues from public repositories, supporting filters like keywords, labels, and states.

Profile-based server split (MCP_PROFILE)

The server can now be launched in three focused profiles, each exposing a smaller, targeted set of tools. This improves LLM tool-selection accuracy and lets you register multiple focused servers in Claude Desktop.

ProfileSet MCP_PROFILE=Tools exposed
Issues (read)issueslist, get, search, filter, labels, comments, duplicates
Admin (write)admincreate, close, reopen, triage, assign, milestone, bulk ops
Analytics & PRsprsPRs, release notes, digest, stale finder, org dashboard, repo stats
All tools(unset)All 31 tools (default, backwards-compatible)

SSE streaming support

The /mcp endpoint now supports Server-Sent Events (SSE) streaming alongside JSON. Clients that send Accept: text/event-stream automatically receive a streaming MCP response. This makes the server fully compatible with Cursor, MCP Inspector, and other streaming-capable MCP clients.

Improved tool descriptions

Every tool now includes a workflow tip explaining how it fits into common task sequences — helping LLMs chain tools together effectively.

New Features

  • Added --stdio flag for Claude Desktop (JSON-RPC over stdin/stdout)
  • Added dual transport: stdio mode for Claude Desktop, HTTP mode for everything else
  • Added IS_PROD flag — chalk-free JSON logs in production, coloured banner in dev
  • Added dotenv/config import so .env is auto-loaded at startup
  • Added structured error handling wrapper (toolHandler) — Octokit errors become friendly MCP error responses instead of crashes
  • Added mcp-clients/ directory with Claude Desktop, Cursor, and ChatGPT configs
  • Deployed to MCPize at https://github-issue-finder.mcpize.run

v1.0.0 — 2026-03-28 (initial release)

Tools (31 total across 10 sections)

Issue Management — list_issues, get_issue, create_issue, close_issue, reopen_issue, search_issues

Labels & Triage — triage_issue, triage_issue_ai, list_labels, filter_issues_by_label, remove_label_from_issue

Comments & Activity — add_comment, get_issue_comments

Pull Requests — list_pull_requests, get_pull_request, release_notes

Analytics & Smart Finders — weekly_digest, find_stale_issues, find_good_first_issues, find_duplicate_issues, get_repo_stats

Repository & Contributors — get_repo_info, list_contributors

Org Dashboard — list_org_repos, org_issue_dashboard

Assignment & Milestones — assign_issue, list_milestones, filter_issues_by_milestone

Batch Operations — bulk_label_issues

Utility — hello, echo

Use Cases

  1. Automated triage: Run find_issues daily with filters like repo:owner/repo label:bug state:open to list priority bugs for team review in Slack bots or dashboards.

  2. Duplicate detection: Before creating a new issue, search with keywords from a proposed title/body using find_issues to retrieve similar open issues and link them.

  3. Release preparation: Query closed issues in a milestone with find_issues to generate changelogs listing fixed bugs and features.

  4. Research assistance: AI agents use it to find historical issues matching user queries, providing context for support tickets or code reviews.

GitHub Issue Finder MCP Server — User Manual

A complete guide for every tool. No GitHub or coding experience required for the basics.


Table of Contents

  1. What is this?
  2. Getting Connected
  3. How to Use Tools
  4. Tool Reference
  5. Workflow Recipes
  6. Common Errors
  7. Server Profiles

1. What is this?

This MCP server gives your AI assistant (Claude, Cursor, or ChatGPT) the ability to read and manage GitHub issues, pull requests, labels, milestones, and more — directly from the chat window.

You talk to your AI normally, and it calls the right tools behind the scenes. You can also call tools explicitly by name.

You need:

  • A GitHub Personal Access Token (PAT) with repo and read:org scopes
  • (Optional) An Anthropic API key for AI-powered issue triage

2. Getting Connected

Claude Desktop (local)

Your claude_desktop_config.json should look like this:

{
  "mcpServers": {
    "github-issue-finder": {
      "command": "node",
      "args": ["C:\\path\\to\\github-issue-finder\\dist\\index.js", "--stdio"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_real_token_here",
        "ANTHROPIC_API_KEY": "sk-ant-your_key_here",
        "NODE_ENV": "development"
      }
    }
  }
}

After saving, fully quit Claude Desktop and reopen it. You should see a hammer icon in the chat input.

Cursor / MCP Inspector (HTTP)

Connect to: http://localhost:8081/mcp

Live Production Server (MCPize)

{
  "url": "https://github-issue-finder.mcpize.run",
  "headers": { "API_KEY": "your_mcpize_api_key" }
}

3. How to Use Tools

You can ask your AI in plain English. Examples:

"List the open issues in facebook/react" "Triage issue #42 in my repo using AI" "Show me stale issues older than 60 days in vercel/next.js" "Generate release notes for microsoft/vscode"

Or you can tell the AI to call a specific tool:

"Call list_issues with owner=vercel repo=next.js state=open"

Key terms:

  • owner — the GitHub username or organization name (e.g. facebook, vercel, your-username)
  • repo — the repository name (e.g. react, next.js)
  • issue_number — the number shown on GitHub after the # in issue titles

4. Tool Reference


Issue Management


list_issues

What it does: Lists issues from a repository. Returns number, title, state, and labels for each issue.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org name
repoYesRepository name
stateNoopenopen, closed, or all
per_pageNo20Number of results (max 100)
pageNo1Page number for pagination

Example prompt:

"Show me the first 50 open issues in vercel/next.js"

Example tool call:

list_issues(owner="vercel", repo="next.js", state="open", per_page=50)

Returns: A numbered list of issues with titles, labels, and assignees.

Workflow tip: Use this first to get issue numbers, then call get_issue for details or triage_issue_ai to classify.


get_issue

What it does: Gets full details of one specific issue — body text, all labels, assignees, milestone, and timestamps.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number (e.g. 42)

Example prompt:

"Get the full details of issue #123 in facebook/react"

Returns: Issue title, state, full body, labels, assignees, milestone, created/updated dates, and URL.

Workflow tip: Use after list_issues to read the full issue before triaging or commenting.


create_issue

What it does: Creates a new issue in a repository.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
titleYesIssue title (max 256 chars)
bodyNo""Issue description (Markdown supported)
labelsNo[]Labels to apply immediately
assigneesNo[]GitHub usernames to assign
milestoneNoMilestone number

Example prompt:

"Create an issue in my-org/my-app titled 'Login button not working on mobile' with label 'bug'"

Best practice: Always call find_duplicate_issues first to make sure a similar issue doesn't already exist.

Returns: Issue number, title, and URL.


close_issue

What it does: Closes an open issue with a reason.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number
reasonNocompletedcompleted (fixed) or not_planned (won't fix)

Example prompt:

"Close issue #55 in my-org/my-app as completed"

Returns: Confirmation with issue number and reason.


reopen_issue

What it does: Reopens a previously closed issue.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number

Example prompt:

"Reopen issue #55 in my-org/my-app — the bug came back"

Returns: Confirmation that the issue is now open.


search_issues

What it does: Searches for issues across GitHub using GitHub's search query syntax. Can search across all public repos or narrow to a specific one.

Parameters:

ParameterRequiredDefaultDescription
queryYesGitHub search query string
sortNoupdatedcreated, updated, or comments
orderNodescasc or desc
per_pageNo10Results per page (max 100)

Example queries:

What you wantQuery string
Open bugs in a specific reporepo:facebook/react is:issue is:open label:bug
Unassigned issues in an orgorg:vercel is:issue is:open no:assignee
Issues you createdis:issue author:your-username
Issues mentioning youis:issue mentions:your-username
High comment count issuesrepo:owner/name is:open comments:>10

Example prompt:

"Search for open unassigned bug issues in vercel/next.js"

Returns: Issue numbers, titles, states, and repo names for all matches.


Labels & Triage


list_labels

What it does: Lists all labels defined in a repository with their descriptions.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name

Example prompt:

"What labels exist in my-org/my-app?"

Returns: Label names with descriptions.

Workflow tip: Always call this before filter_issues_by_label so you know the exact label names to use.


filter_issues_by_label

What it does: Gets all issues that have a specific label applied.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
labelYesExact label name (case-sensitive)
stateNoopenopen, closed, or all

Example prompt:

"Show me all open issues labeled 'bug' in my-org/my-app"

Returns: List of issues with that label.


triage_issue

What it does: Automatically classifies an issue as bug, enhancement, question, or documentation using keyword matching — then applies the label to the issue.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number

Example prompt:

"Triage issue #42 in my-org/my-app"

How it works: Reads the issue title and body, matches keywords like "crash", "feature request", "how do I", and applies the closest matching label.

Returns: The label that was applied.

Note: No API key needed. Use triage_issue_ai for better accuracy.


triage_issue_ai

What it does: Classifies an issue using Claude Haiku AI for higher accuracy than keyword matching. Optionally applies the label automatically.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number
apply_labelNotrueSet to false to preview without writing

Example prompt:

"Use AI to triage issue #42 in my-org/my-app but don't apply the label yet"

Requires: ANTHROPIC_API_KEY environment variable must be set.

Returns: The AI-chosen label, and whether it was applied.

Workflow tip: Set apply_label=false first to preview, then call again with apply_label=true to confirm.


remove_label_from_issue

What it does: Removes a specific label from an issue.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number
labelYesExact label name to remove

Example prompt:

"Remove the 'wontfix' label from issue #12 in my-org/my-app"

Returns: Confirmation of removal.


Comments & Activity


add_comment

What it does: Posts a comment on an issue or pull request.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue or PR number
bodyYesComment text (Markdown supported)

Example prompt:

"Add a comment to issue #42 in my-org/my-app saying 'This is being looked into by the platform team.'"

Markdown support: You can use bold, code blocks, lists, links, etc.

Returns: Comment ID and confirmation.


get_issue_comments

What it does: Retrieves all comments on an issue, in chronological order.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number

Example prompt:

"Show me all comments on issue #42 in my-org/my-app"

Returns: Each comment with its author, timestamp, and full text.


Pull Requests


list_pull_requests

What it does: Lists pull requests in a repository, with state and base branch filtering.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
stateNoopenopen, closed, or all
baseNoFilter by base branch (e.g. main)
per_pageNo20Number of results (max 100)

Example prompt:

"Show all open pull requests targeting the main branch in my-org/my-app"

Returns: PR numbers, titles, authors, and base/head branches.


get_pull_request

What it does: Gets full details of a single pull request including code change stats.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
pull_numberYesPR number

Example prompt:

"Get the details of PR #88 in my-org/my-app"

Returns: Title, state, merged status, author, base/head branch, lines added, lines deleted, files changed, and URL.


release_notes

What it does: Generates a Markdown changelog from recently merged pull requests. Ready to paste into a GitHub Release.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
limitNo10Max merged PRs to include (max 50)

Example prompt:

"Generate release notes for the last 20 merged PRs in my-org/my-app"

Returns: A formatted Markdown list like:

## Proposed Release Notes

- Fix login crash on mobile (#101) by @alice
- Add dark mode toggle (#98) by @bob
- Upgrade dependencies (#95) by @charlie

Analytics & Smart Finders


weekly_digest

What it does: Summarizes the past 7 days of repository activity — issues opened/updated, PRs, and commits.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name

Example prompt:

"Give me a weekly digest for my-org/my-app"

Returns: Issue count, PR count, and commit count for the last 7 days.


find_stale_issues

What it does: Finds open issues that have had no activity (comments, updates) for longer than a threshold number of days.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
daysNo30Inactivity threshold in days
limitNo20Max results

Example prompt:

"Find issues in my-org/my-app with no activity for 60 days"

Returns: Issue numbers, titles, and date of last update.

Workflow tip: Use the returned issue numbers with bulk_label_issues to mark them all as stale in one call.


find_good_first_issues

What it does: Finds open issues labeled good first issue — these are the best starting points for new contributors.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
limitNo10Max results

Example prompt:

"Find good first issues in facebook/react for a new contributor"

Returns: Issue numbers, titles, and direct GitHub URLs.


find_duplicate_issues

What it does: Searches for existing open issues similar to a title you provide, to prevent duplicate submissions.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
titleYesTitle of the issue you want to create
thresholdNo5Max similar issues to return

Example prompt:

"Check if there are any existing issues about 'login page crashes on Safari' in my-org/my-app"

Returns: Similar existing issues (with links), or confirmation that it's safe to create a new one.

Best practice: Always call this before create_issue.


get_repo_stats

What it does: Gets headline statistics for a repository.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name

Example prompt:

"What are the stats for microsoft/vscode?"

Returns: Stars, forks, watchers, open issues count, primary language, and topics.


Repository Info


get_repo_info

What it does: Gets detailed metadata about a repository.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name

Example prompt:

"Get the full info for my-org/my-app"

Returns: Visibility (public/private), default branch, license, homepage, clone URL, archived status.


list_contributors

What it does: Lists the top contributors to a repository, sorted by commit count.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
limitNo10Number of contributors to return

Example prompt:

"Who are the top 5 contributors to my-org/my-app?"

Returns: Ranked list with GitHub username and commit count.

Workflow tip: Use the returned usernames with assign_issue to assign issues to active contributors.


Org Dashboard


list_org_repos

What it does: Lists repositories in a GitHub organization, sorted by most recently updated.

Parameters:

ParameterRequiredDefaultDescription
orgYesOrganization name
typeNopublicall, public, private, forks, or sources
per_pageNo30Number of repos

Example prompt:

"List all public repos in the vercel organization"

Returns: Repo names, star counts, and open issue counts.


org_issue_dashboard

What it does: Aggregates open issue counts across all repos in an org, ranked by which repos need the most attention.

Parameters:

ParameterRequiredDefaultDescription
orgYesOrganization name
topNo10How many repos to show

Example prompt:

"Show me the org issue dashboard for microsoft — which repos have the most open issues?"

Returns: Total open issues across the org, and a ranked list of the repos with the most issues.

Workflow tip: Use this first when managing a multi-repo organization. Then drill into specific repos with list_issues or find_stale_issues.


Assignment & Milestones


assign_issue

What it does: Assigns one or more GitHub users to an issue.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numberYesIssue number
assigneesYesList of GitHub usernames, e.g. ["alice", "bob"]

Example prompt:

"Assign issue #42 in my-org/my-app to alice and bob"

Returns: Issue number and confirmed assignee list.

Workflow tip: Use list_contributors first to find the best person based on who is most active in the repo.


list_milestones

What it does: Lists all milestones in a repository with their open/closed issue counts and due dates.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
stateNoopenopen, closed, or all

Example prompt:

"Show all open milestones in my-org/my-app"

Returns: Milestone numbers, titles, open/closed issue counts, and due dates.

Workflow tip: Use this to get milestone numbers before calling filter_issues_by_milestone.


filter_issues_by_milestone

What it does: Gets all issues assigned to a specific milestone.

Parameters:

ParameterRequiredDefaultDescription
ownerYesGitHub username or org
repoYesRepository name
milestone_numberYesMilestone number (from list_milestones)
stateNoopenopen, closed, or all

Example prompt:

"Show me all open issues in milestone #3 of my-org/my-app"

Returns: Issue list for the milestone.


Batch Operations


bulk_label_issues

What it does: Applies a single label to multiple issues at once. Maximum 20 issues per call.

Parameters:

ParameterRequiredDescription
ownerYesGitHub username or org
repoYesRepository name
issue_numbersYesList of issue numbers, e.g. [12, 15, 23, 31]
labelYesLabel name to apply to all issues

Example prompt:

"Apply the 'needs-review' label to issues #10, #14, #22, and #35 in my-org/my-app"

Returns: Confirmation of which issues were labeled.

Workflow tip:

  1. Call find_stale_issues to get a list of stale issue numbers
  2. Copy the numbers into bulk_label_issues with label="stale"
  3. Done — all stale issues labeled in one shot

Utility / Testing


hello

What it does: Returns a greeting. Used to test that the server is connected and responding.

Parameters:

ParameterRequiredDescription
nameYesName to greet

Example prompt:

"Call the hello tool with name='GitHub'"

Returns: { "message": "Hello, GitHub!" }


echo

What it does: Echoes text back with a timestamp. Used to confirm connectivity and response time.

Parameters:

ParameterRequiredDescription
textYesText to echo back

Example prompt:

"Echo 'connection test' back to me"

Returns: { "echo": "connection test", "timestamp": "2026-04-12T..." }


5. Workflow Recipes

Triage all unlabeled issues in a repo

  1. list_issues — get open issues
  2. Filter ones with no labels
  3. For each: triage_issue_ai with apply_label=true

Weekly maintenance routine

  1. weekly_digest — see what happened this week
  2. find_stale_issues(days=30) — find neglected issues
  3. bulk_label_issues — label them all as stale
  4. org_issue_dashboard — check which repos are accumulating the most issues

Create an issue the right way

  1. find_duplicate_issues — make sure it doesn't already exist
  2. list_labels — see what labels are available
  3. list_contributors — find who to assign it to
  4. list_milestones — choose the right milestone
  5. create_issue — create with labels, assignees, milestone in one call

Review a release

  1. list_pull_requests(state="closed") — see recently merged PRs
  2. release_notes(limit=20) — get a formatted changelog
  3. Paste into your GitHub Release

Onboard a new contributor

  1. find_good_first_issues — find beginner-friendly tasks
  2. get_issue — read the full details of a promising one
  3. add_comment — welcome them and explain the task
  4. assign_issue — assign it to them

Deep-dive into a busy org

  1. org_issue_dashboard — rank repos by open issues
  2. list_issues on the top repo — see what's open
  3. find_stale_issues — identify abandoned issues
  4. triage_issue_ai on unlabeled ones — classify in bulk

6. Common Errors

Error messageCauseFix
GitHub authentication failedGITHUB_TOKEN is missing or invalidCheck your token in .env or Claude Desktop config
Permission deniedYour token doesn't have repo scopeRegenerate token with repo and read:org scopes
Rate limit exceededToo many requests without a tokenAdd a valid GITHUB_TOKEN to get 5000 requests/hour
Resource not foundWrong owner, repo, or issue numberDouble-check spelling — GitHub is case-sensitive for some names
Invalid inputA parameter value is out of rangeCheck per_page ≤ 100, issue_number is a positive integer
ANTHROPIC_API_KEY is not setAI triage tools need this keyAdd ANTHROPIC_API_KEY to your config or .env

7. Server Profiles

To reduce tool clutter in Claude's tool menu and improve AI tool selection, you can run the server in a focused profile:

# Only issue read/search tools (12 tools)
MCP_PROFILE=issues node dist/index.js --stdio

# Only write/mutation tools (10 tools)
MCP_PROFILE=admin node dist/index.js --stdio

# Only PR, analytics, and org tools (9 tools)
MCP_PROFILE=prs node dist/index.js --stdio

# All tools — default
node dist/index.js --stdio

Recommended Claude Desktop setup (3 focused servers):

Register all three profiles as separate servers in claude_desktop_config.json. Claude will see three small, focused tool sets instead of one large 31-tool list. See mcp-clients/claude-desktop.json → local-split for the exact config.

Which tools belong to which profile?

Toolissuesadminprs
list_issues
get_issue
search_issues
find_duplicate_issues
list_labels
filter_issues_by_label
get_issue_comments
create_issue
close_issue
reopen_issue
triage_issue
triage_issue_ai
remove_label_from_issue
add_comment
assign_issue
list_milestones
filter_issues_by_milestone
bulk_label_issues
list_pull_requests
get_pull_request
release_notes
weekly_digest
find_stale_issues
find_good_first_issues
get_repo_stats
get_repo_info
list_contributors
list_org_repos
org_issue_dashboard
hello
echo

Who This Is For

Repository maintainers tracking project health, developers integrating issue data into custom tools or CI pipelines, open-source contributors researching repos, and DevOps teams automating GitHub workflows.