Once configured, the Bugzilla MCP Server provides several tools that your AI assistant can use to interact with Bugzilla. This guide provides comprehensive examples, response formats, and real-world usage patterns for each tool.
bug_info - Get Bug InformationRetrieves information about a bug by ID, including status, assignee, priority and other metadata.
By default, empty fields (such as unused cf_* custom fields) are left out to save tokens. The update_token form token is always removed.
Parameters:
id (int, required) - The Bugzilla bug IDfull (bool, optional) - Return every field, including empty ones (default: false)include_fields (list of strings, optional) - Only fetch these fields, e.g. ["status", "assigned_to", "cf_qatouch_id"]Example Usage:
Get information about bug #12345
What are the details of bug 12345?
Show me everything about bug #12345
Response Format: The tool returns a dictionary of the bug's non-empty fields:
{
"id": 12345,
"summary": "Bug title/summary",
"status": "NEW",
"resolution": "",
"product": "Firefox",
"component": "Core",
"version": "120",
"platform": "All",
"op_sys": "All",
"priority": "P1",
"severity": "S1",
"assigned_to": "developer@example.com",
"reporter": "user@example.com",
"creation_time": "2024-01-15T10:30:00Z",
"last_change_time": "2024-01-20T14:22:00Z",
"cc": ["reviewer@example.com"],
"keywords": ["crash", "regression"],
"whiteboard": "[needs-review]",
"flags": [...],
// ... and many more fields
}
Common Use Cases:
bug_comments - Get Bug CommentsRetrieves comments for a specific bug. By default, only public comments are returned, but you can request private comments if you have the necessary permissions.
Parameters:
id (int, required) - The Bugzilla bug IDinclude_private_comments (bool, optional) - Include private comments (default: false)Example Usage:
Get comments for bug #12345
Show me all comments for bug 12345 including private ones
What have people said about bug #12345?
Response Format: Returns a list of comment objects:
[
{
"id": 1,
"author": "developer@example.com",
"text": "I've identified the issue in the code...",
"time": "2024-01-15T10:35:00Z",
"is_private": false,
"count": 0
},
{
"id": 2,
"author": "reviewer@example.com",
"text": "Internal note: needs security review",
"time": "2024-01-16T09:20:00Z",
"is_private": true,
"count": 1
}
]
Important Notes:
include_private_comments=true and your API key has permission to view themadd_comment - Add Comment to BugAdds a comment to a bug. Comments can be public (visible to all) or private (visible only to users with appropriate permissions).
Parameters:
bug_id (int, required) - The Bugzilla bug IDcomment (string, required) - The comment text to addis_private (bool, optional) - Make the comment private (default: false)Example Usage:
Add a comment to bug #12345: "This issue has been fixed in the latest release"
Add a private comment to bug #12345: "Internal note: needs review before release"
Post a comment: "Fixed in commit abc123def" to bug 12345
Response Format: Returns the ID of the created comment:
{
"id": 42
}
Common Use Cases:
bugs_quicksearch - Search BugsSearches for bugs using Bugzilla's powerful quicksearch syntax. Returns a list of bugs matching your criteria with essential fields.
Parameters:
query (string, required) - Quicksearch query stringlimit (int, optional) - Maximum number of results (default: 50, max: typically 1000)offset (int, optional) - Offset for pagination (default: 0)Example Usage:
Search for bugs assigned to john@example.com
Find all open bugs in the Firefox product
Search for bugs with status NEW or ASSIGNED
Show me high priority bugs in the Core component
Response Format: Returns a list of bugs with essential fields:
[
{
"bug_id": 12345,
"product": "Firefox",
"component": "Core",
"assigned_to": "developer@example.com",
"status": "NEW",
"resolution": "",
"summary": "Bug title/summary",
"last_updated": "2024-01-20T14:22:00Z"
},
{
"bug_id": 12346,
"product": "Firefox",
"component": "DOM",
"assigned_to": "another@example.com",
"status": "ASSIGNED",
"resolution": "",
"summary": "Another bug",
"last_updated": "2024-01-19T09:15:00Z"
}
]
Quicksearch Syntax Examples:
Basic Searches:
assignedto:john@example.com - Bugs assigned to a specific userreporter:user@example.com - Bugs reported by a userproduct:Firefox - Bugs in a specific productcomponent:Core - Bugs in a specific componentstatus:NEW - Bugs with a specific statuspriority:P1 - Bugs with a specific priorityseverity:S1 - Bugs with a specific severityCombined Searches:
product:Firefox status:NEW - New bugs in Firefoxassignedto:john@example.com status:ASSIGNED - Assigned bugs for a usercomponent:Core priority:P1,P2 - High priority Core bugsstatus:NEW,ASSIGNED product:Firefox - Open Firefox bugsAdvanced Searches:
keywords:crash - Bugs with specific keywordswhiteboard:[needs-review] - Bugs with whiteboard tagscc:reviewer@example.com - Bugs CC'd to a userresolution:FIXED - Fixed bugsresolution:--- - Unresolved bugsPagination:
# First page (default)
bugs_quicksearch(query="product:Firefox", limit=50, offset=0)
# Second page
bugs_quicksearch(query="product:Firefox", limit=50, offset=50)
# Third page
bugs_quicksearch(query="product:Firefox", limit=50, offset=100)
learn_quicksearch_syntax tool to get the complete documentation for your Bugzilla instance's quicksearch syntax.learn_quicksearch_syntax - Get Quicksearch DocumentationRetrieves Bugzilla's quicksearch syntax documentation directly from your Bugzilla instance. This helps AI assistants learn the available search options.
Parameters: None
Example Usage:
Show me the quicksearch syntax documentation
How do I search for bugs?
What search options are available?
Response Format: Returns HTML documentation from your Bugzilla instance containing:
When to Use:
server_url - Get Server URLReturns the base URL of your configured Bugzilla instance.
Parameters: None
Example Usage:
What's the Bugzilla server URL?
Get the server URL
Response Format: Returns a string with the base URL:
"https://bugzilla.example.com"
Use Cases:
bug_url - Get Bug URLGenerates a direct link to view a specific bug in your Bugzilla instance.
Parameters:
bug_id (int, required) - The Bugzilla bug IDExample Usage:
Get the URL for bug #12345
Give me a link to bug 12345
What's the web URL for bug #12345?
Response Format: Returns a complete URL string:
"https://bugzilla.example.com/show_bug.cgi?id=12345"
Use Cases:
bug_attachments - List AttachmentsLists a bug's attachments without the file data.
Parameters:
bug_id (int, required)Returns id, file_name, content_type, size, summary, is_patch, is_obsolete and flags for each attachment.
get_attachment - Read an AttachmentReturns one attachment's metadata plus its content, in a form the assistant can use directly:
| Attachment type | Returned as |
|---|---|
Images (image/*) | An image, so the assistant can see screenshots |
| Text, CSV, JSON, XML, patches | Text |
| Other binaries, or files over 10 MB | Metadata and a link to download it |
Parameters:
attachment_id (int, required): from bug_attachmentsExample Usage:
What does the screenshot on bug #12345 show?
Read the log attached to bug 12345
download_attachments / download_attachment - Save to Disk (local server only)Save a bug's attachments, or one attachment, to a folder on the machine running the server (dest_dir, default tmp/ in the project).
get_attachment there.update_bug - Update BugsChanges one or more bugs in a single call.
Parameters:
ids (int or list of int, required): bugs to updatedry_run (bool, optional): return the planned changes and each bug's current values, without changing anythingstatus, resolution, assigned_to, severity, priority, whiteboard, target_milestone, version, summary, product, component, op_sys, platform, qa_contact, urlcomment (string) and comment_is_private (bool): add a comment with the changedupe_of (int): mark as a duplicate of another bugkeywords, cc, see_also, blocks, depends_on: {"add": [...], "remove": [...]}. keywords, blocks and depends_on also accept {"set": [...]}extra_fields (dict): custom fields, e.g. {"cf_qatouch_id": "123"}Example Usage:
Close bug #12345 as FIXED with a comment linking the commit
Reassign bug 12345 to alice@example.com and CC bob@example.com
Mark bug 12346 as a duplicate of 12345
Show me what would change if you closed bugs 101-110 as WONTFIX (dry run)
With dry_run: true, the result looks like this:
{
"dry_run": true,
"changes": {"status": "RESOLVED", "resolution": "FIXED"},
"current": {"12345": {"status": "ASSIGNED", "resolution": ""}},
"not_found": []
}
update_bug is marked destructive, so MCP clients that honour tool hints ask before running it. Your Bugzilla account's permissions decide what it can actually change.create_bug - File a BugParameters:
product, component, summary, version, description (all required)severity, priority, assigned_to, keywords, target_milestoneReturns {"id": <new bug id>}. Use list_products and get_product_components first to find valid values.
upload_attachment - Attach a FileParameters:
bug_id (int, required), summary (string, required)text: plain text such as a log or patch (file_name defaults to attachment.txt)data_base64: base64 file content (file_name required)file_path: a file on the server's machine, local server onlyfile_name, content_type (auto-detected), comment, is_patchReturns {"attachment_id": ..., "bug_id": ...}.
tag_comment - Tag a CommentAdds or removes tags on a comment (comment_id, add, remove), e.g. fix-candidate or needs-review. Requires comment tagging to be enabled on your Bugzilla.
bug_history (bug_id, optional new_since ISO date): who changed what and when. Useful for regressions.bug_dependencies (bug_id): the bugs it blocks and depends on.duplicate_chain (bug_id, optional max_depth): follows dupe_of links to the original bug.bugs_info (ids): details for several bugs in one request.bugs_comments (ids): comments for several bugs in parallel. A bug that fails to load returns {"error": ...} instead of comments.bugs_analysis_context (ids): bug details plus the first and last two comments of each, sized for an assistant's context.classify_bugs_heuristics (ids): groups bugs using only their status and resolution. See triage rules.analyze_bugs_statistics (ids): counts and percentages by classification, product, component and assignee, plus severity/priority of the bugs still to fix.classify_bugs_heuristics and analyze_bugs_statistics sort each bug with these rules, checked in order:
| Group | Rule | Examples |
|---|---|---|
invalid | Status RESOLVED, VERIFIED or CLOSED and resolution INVALID, WONTFIX, DUPLICATE, WORKSFORME or NOTABUG | RESOLVED DUPLICATE, CLOSED WONTFIX |
to_fix | Status NEW, ASSIGNED, REOPENED or UNCONFIRMED | NEW, REOPENED |
review_needed | Anything else | RESOLVED FIXED, VERIFIED FIXED, or a custom status such as CONFIRMED or IN_PROGRESS |
The rules don't read summaries, comments or activity. If your Bugzilla uses custom open statuses, expect those bugs under review_needed. Use bugs_analysis_context when the assistant needs the discussion too.
bugs_advanced_search: filters combined with AND, as an alternative to quicksearch syntax.
"NEW" or ["NEW", "ASSIGNED"]): product, component, status, resolution, severity, priority, keywords, version, target_milestoneassigned_to, creator, creation_time, last_change_time (ISO date: changed since)limit (default 50), offsetget_user (names or ids) and search_users (match, limit): find the right login before assigning or CC-ing someone.list_products and get_product_components (product_name): valid products and components, with default assignees, before filing a bug.Every tool tells MCP clients what it does:
| Hint | Tools |
|---|---|
| Read-only | All reading, search, batch, user and product tools |
| Adds data | add_comment, create_bug, upload_attachment, tag_comment, download_attachment(s) |
| Destructive | update_bug |
Clients such as Claude can use these to run reads without asking and confirm before changes.
All tools except the read-only ones are hidden until you turn off read-only mode.
bug_info and bug_comments for the reportbug_attachments, then get_attachment on any screenshot or logbug_history if it looks like a regressionupdate_bug with status: RESOLVED, resolution: FIXED and a comment linking the changeScenario: A user reports a bug and you need to investigate it.
1. Get bug information: "Get details about bug #12345"
2. Read comments: "Show me all comments for bug #12345"
3. Check related bugs: "Search for bugs in the same component as bug #12345"
4. Add investigation note: "Add comment to bug #12345: 'Investigating the root cause...'"
Scenario: Review and manage bugs assigned to you.
1. Find your bugs: "Search for bugs assigned to me with status NEW or ASSIGNED"
2. Review each bug: "Get information about bug #12345"
3. Check comments: "Get comments for bug #12345"
4. Update status: "Add comment to bug #12345: 'Working on this, ETA: tomorrow'"
Scenario: Triage new bugs in a product.
1. Find new bugs: "Search for bugs in product Firefox with status NEW"
2. Review each bug: Get bug information for each result
3. Check duplicates: "Search for bugs with similar summary"
4. Assign or update: "Add comment to bug #12345: 'Triaged: assigned to team X'"
Scenario: Find and verify bugs fixed in a release.
1. Find fixed bugs: "Search for bugs with resolution FIXED in product Firefox"
2. Verify fixes: "Get information about bug #12345"
3. Check comments: "Get comments for bug #12345 to see fix details"
4. Generate report: Use bug URLs to create a release notes document
Example: Get comprehensive bug information
1. Search: "Find bugs assigned to me"
2. For each result:
- Get full details: bug_info(id)
- Get comments: bug_comments(id)
- Get URL: bug_url(id)
Best Practices:
Example:
# Too broad (may return too many results)
"Search for all bugs"
# Better (more specific)
"Search for bugs in product Firefox with status NEW"
# Best (very specific)
"Search for bugs in product Firefox, component Core, status NEW, priority P1"
The tools provide clear error messages:
Problem: Search returns empty results
Solutions:
learn_quicksearch_syntax to verify available fieldsProblem: Getting errors when trying to add comments
Solutions:
Problem: Private comments not returned even with include_private_comments=true
Solutions:
Problem: Search returns hundreds of results
Solutions: