Setting the file. One moment.
Subchapter 193.8
references/search.mdMarkdown7 KBView on GitHub
The search_issues MCP tool uses GitHub’s issue search query format for cross-repo searches, supporting implicit-AND queries, date ranges, and metadata filters (but not explicit OR/NOT operators).
There are three ways to find issues, each with different capabilities:
| Capability | list_issues (MCP) | search_issues (MCP) | Advanced search (gh api) |
|---|---|---|---|
| Scope | Single repo only | Cross-repo, cross-org | Cross-repo, cross-org |
Issue field filters (field.priority:P0) | No | No | Yes (dot notation) |
Issue type filter (type:Bug) | No | Yes | Yes |
| Boolean logic (AND/OR/NOT, nesting) | No | Yes (implicit AND only) | Yes (explicit AND/OR/NOT) |
| Label/state/date filters | Yes | Yes | Yes |
| Assignee/author/mentions | No | Yes | Yes |
Negation (-label:x, no:label) | No | Yes | Yes |
| Text search (title/body/comments) | No | Yes | Yes |
since filter | Yes | No | No |
| Result limit | No cap (paginate all) | 1,000 max | 1,000 max |
| How to call | MCP tool directly | MCP tool directly | gh api with advanced_search=true |
Decision guide:
list_issuessearch_issuesgh api with advanced_search=trueThe query parameter is a string of search terms and qualifiers. A space between terms is implicit AND.
repo:owner/repo # Single repo (auto-added if you pass owner+repo params)
org:github # All repos in an org
user:octocat # All repos owned by user
in:title # Search only in title
in:body # Search only in body
in:comments # Search only in commentsis:open # Open issues (auto-added: is:issue)
is:closed # Closed issues
reason:completed # Closed as completed
reason:"not planned" # Closed as not plannedauthor:username # Created by
assignee:username # Assigned to
mentions:username # Mentions user
commenter:username # Has comment from
involves:username # Author OR assignee OR mentioned OR commenter
author:@me # Current authenticated user
team:org/team # Team mentionedlabel:"bug" # Has label (quote multi-word labels)
label:bug label:priority # Has BOTH labels (AND)
label:bug,enhancement # Has EITHER label (OR)
-label:wontfix # Does NOT have label
milestone:"v2.0" # In milestone
project:github/57 # In project board
type:"Bug" # Issue typeno:label # No labels assigned
no:milestone # No milestone
no:assignee # Unassigned
no:project # Not in any projectAll date qualifiers support >, <, >=, <=, and range (..) operators with ISO 8601 format:
created:>2026-01-01 # Created after Jan 1
updated:>=2026-03-01 # Updated since Mar 1
closed:2026-01-01..2026-02-01 # Closed in January
created:<2026-01-01 # Created before Jan 1linked:pr # Issue has a linked PR
-linked:pr # Issues not yet linked to any PR
linked:issue # PR is linked to an issuecomments:>10 # More than 10 comments
comments:0 # No comments
interactions:>100 # Reactions + comments > 100
reactions:>50 # More than 50 reactionsUse AND, OR, and parentheses (up to 5 levels deep, max 5 operators):
label:bug AND assignee:octocat
assignee:octocat OR assignee:hubot
(type:"Bug" AND label:P1) OR (type:"Feature" AND label:P1)
-author:app/dependabot # Exclude bot issuesA space between terms without an explicit operator is treated as AND.
Unassigned bugs:
repo:owner/repo type:"Bug" no:assignee is:openIssues closed this week:
repo:owner/repo is:closed closed:>=2026-03-01Stale open issues (no updates in 90 days):
repo:owner/repo is:open updated:<2026-01-01Open issues without a linked PR (needs work):
repo:owner/repo is:open -linked:prIssues I’m involved in across an org:
org:github involves:@me is:openHigh-activity issues:
repo:owner/repo is:open comments:>20Issues by type and priority label:
repo:owner/repo type:"Epic" label:P1 is:openReliability warning: The
field.name:valuesearch qualifier syntax is experimental and may return 0 results even when matching issues exist. For reliable filtering by field values, use the GraphQL bulk query approach documented in issue-fields.md.
Issue fields can theoretically be searched via the field.name:value qualifier using advanced search mode. This works in the web UI but results from the API are inconsistent.
Add advanced_search=true as a query parameter:
gh api "search/issues?q=org:github+field.priority:P0+type:Epic+is:open&advanced_search=true" \
--jq '.items[] | "#\(.number): \(.title)"'Use type: ISSUE_ADVANCED instead of type: ISSUE:
{
search(query: "org:github field.priority:P0 type:Epic is:open", type: ISSUE_ADVANCED, first: 10) {
issueCount
nodes {
... on Issue { number title }
}
}
}The syntax uses dot notation with the field’s slug name (lowercase, hyphens for spaces):
field.priority:P0 # Single-select field equals value
field.priority:P1 # Different option value
field.target-date:>=2026-04-01 # Date comparison
has:field.priority # Has any value set
no:field.priority # Has no value setMCP limitation: The search_issues MCP tool does not pass advanced_search=true. You must use gh api directly for issue field searches.
P0 epics across an org:
org:github field.priority:P0 type:Epic is:openIssues with a target date this quarter:
org:github field.target-date:>=2026-04-01 field.target-date:<=2026-06-30 is:openOpen bugs missing priority:
org:github no:field.priority type:Bug is:openlist_issues if you need all issues)advanced_search=true (REST) or ISSUE_ADVANCED (GraphQL); not available through MCP search_issues