Jira MCP Server

Instructions

Implementation Reference

• src/mcp_server_jira/server.py:415-474 (handler)

  Primary tool handler: performs paginated JQL search using JiraV3APIClient, respects max_results limit, returns raw API issue data.
  async def search_jira_issues( self, jql: str, max_results: int = 10 ) -> List[JiraIssueResult]: """Search for issues using JQL via v3 REST API with pagination support""" logger.info("Starting search_jira_issues...") try: # Use v3 API client v3_client = self._get_v3_api_client() # Collect all issues from all pages all_issues = [] start_at = 0 page_size = min(max_results, 100) # Jira typically limits to 100 per page while True: logger.debug(f"Fetching page starting at {start_at} with page size {page_size}") response_data = await v3_client.search_issues( jql=jql, start_at=start_at, max_results=page_size ) # Extract issues from current page page_issues = response_data.get("issues", []) all_issues.extend(page_issues) logger.debug(f"Retrieved {len(page_issues)} issues from current page. Total so far: {len(all_issues)}") # Check if we've reached the user's max_results limit if len(all_issues) >= max_results: # Trim to exact max_results if we exceeded it all_issues = all_issues[:max_results] logger.debug(f"Reached max_results limit of {max_results}, stopping pagination") break # Check if this is the last page according to API is_last = response_data.get("isLast", True) if is_last: logger.debug("API indicates this is the last page, stopping pagination") break # If we have more pages, prepare for next iteration start_at = len(all_issues) # Use actual number of issues retrieved so far # Adjust page size for next request to not exceed max_results remaining_needed = max_results - len(all_issues) page_size = min(remaining_needed, 100) # Return raw issues list for full JSON data logger.info(f"Returning raw issues ({len(all_issues)}) for JQL: {jql}") return all_issues except Exception as e: error_msg = f"Failed to search issues: {type(e).__name__}: {str(e)}" logger.error(error_msg, exc_info=True) print(error_msg) raise ValueError(error_msg)
• src/mcp_server_jira/server.py:1199-1216 (registration)

  Tool registration including name, description, and input schema definition.
  Tool( name=JiraTools.SEARCH_ISSUES.value, description="Search for Jira issues using JQL (Jira Query Language)", inputSchema={ "type": "object", "properties": { "jql": { "type": "string", "description": "JQL query string (e.g., 'project = MYPROJ AND status = \"In Progress\"')", }, "max_results": { "type": "integer", "description": "Maximum number of results to return (default: 10)", }, }, "required": ["jql"], }, ),
• src/mcp_server_jira/server.py:1426-1434 (handler)

  Tool dispatcher case in call_tool() that extracts arguments and invokes the search_jira_issues handler.
  case JiraTools.SEARCH_ISSUES.value: logger.info("Calling async tool search_jira_issues...") jql = arguments.get("jql") if not jql: raise ValueError("Missing required argument: jql") max_results = arguments.get("max_results", 10) result = await jira_server.search_jira_issues(jql, max_results) logger.info("Async tool search_jira_issues completed.")
• src/mcp_server_jira/jira_v3_api.py:527-601 (helper)

  Low-level helper: makes HTTP request to Jira v3 /search/jql endpoint with JQL and pagination params.
  async def search_issues( self, jql: str, start_at: int = 0, max_results: int = 50, fields: Optional[str] = None, expand: Optional[str] = None, properties: Optional[list] = None, fields_by_keys: Optional[bool] = None, fail_fast: Optional[bool] = None, reconcile_issues: Optional[list] = None, ) -> Dict[str, Any]: """ Search for issues using JQL enhanced search (GET) via v3 REST API. Searches for issues using JQL. Recent updates might not be immediately visible in the returned search results. If you need read-after-write consistency, you can utilize the reconcileIssues parameter to ensure stronger consistency assurances. This operation can be accessed anonymously. Args: jql: JQL query string start_at: Index of the first issue to return (default: 0) max_results: Maximum number of results to return (default: 50) fields: Comma-separated list of fields to include in response expand: Use expand to include additional information about issues properties: List of issue properties to include in response fields_by_keys: Reference fields by their key (rather than ID) fail_fast: Fail fast when JQL query validation fails reconcile_issues: List of issue IDs to reconcile for read-after-write consistency Returns: Dictionary containing search results with: - issues: List of issue dictionaries - isLast: Boolean indicating if this is the last page - startAt: Starting index of results - maxResults: Maximum results per page - total: Total number of issues matching the query Raises: ValueError: If the API request fails or JQL is invalid """ if not jql: raise ValueError("jql parameter is required") # Build query parameters params = { "jql": jql, "startAt": start_at, "maxResults": max_results, } # Add optional parameters if provided params["fields"] = fields if fields is not None else "*all" if expand: params["expand"] = expand if properties: params["properties"] = properties if fields_by_keys is not None: params["fieldsByKeys"] = fields_by_keys if fail_fast is not None: params["failFast"] = fail_fast if reconcile_issues: params["reconcileIssues"] = reconcile_issues # Remove None values params = {k: v for k, v in params.items() if v is not None} endpoint = "/search/jql" logger.debug(f"Searching issues with v3 API endpoint: {endpoint}") logger.debug(f"Search params: {params}") response_data = await self._make_v3_api_request("GET", endpoint, params=params) logger.debug(f"Search issues API response: {json.dumps(response_data, indent=2)}") return response_data
• src/mcp_server_jira/server.py:76-94 (schema)

  Pydantic model intended for issue results (though handler returns raw dicts).
  class JiraIssueResult(BaseModel): key: str summary: str description: Optional[str] = None status: Optional[str] = None assignee: Optional[str] = None reporter: Optional[str] = None created: Optional[str] = None updated: Optional[str] = None fields: Optional[Dict[str, Any]] = None comments: Optional[List[Dict[str, Any]]] = None watchers: Optional[Dict[str, Any]] = None attachments: Optional[List[Dict[str, Any]]] = None subtasks: Optional[List[Dict[str, Any]]] = None project: Optional[Dict[str, Any]] = None issue_links: Optional[List[Dict[str, Any]]] = None worklog: Optional[List[Dict[str, Any]]] = None timetracking: Optional[Dict[str, Any]] = None