Search & Fields

Search Issues¶

Search Jira issues using JQL (Jira Query Language).

Parameters:

Parameter	Type	Required	Description
`jql`	`string`	Yes	JQL query string (Jira Query Language). Examples: - Find Epics: "issuetype = Epic AND project = PROJ" - Find issues in Epic: "parent = PROJ-123" - Find by status: "status = 'In Progress' AND project = PROJ" - Find by assignee: "assignee = currentUser()" - Find recently updated: "updated >= -7d AND project = PROJ" - Find by label: "labels = frontend AND project = PROJ" - Find by priority: "priority = High AND project = PROJ"
`fields`	`string`	No	(Optional) Comma-separated fields to return in the results. Use '*all' for all fields, or specify individual fields like 'summary,status,assignee,priority'
`limit`	`integer`	No	Maximum number of results (1-50)
`start_at`	`integer`	No	Starting index for pagination (0-based)
`projects_filter`	`string`	No	(Optional) Comma-separated list of project keys to filter results by. Overrides the environment variable JIRA_PROJECTS_FILTER if provided.
`expand`	`string`	No	(Optional) fields to expand. Examples: 'renderedFields', 'transitions', 'changelog'
`page_token`	`string`	No	Pagination token from a previous search result. Cloud only — Server/DC uses `start_at` for pagination.
Example:

{"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20}

Tip

Always use ORDER BY for deterministic results. Use fields parameter to limit returned data for faster queries.

Warning

Some JQL functions (e.g., issueHistory()) are Cloud-only.

Tip

Cloud supports cursor-based pagination via page_token for deterministic results across large datasets. The token is returned in the next_page_token field of search results.

Search Fields¶

Search Jira fields by keyword with fuzzy match.

Parameters:

Parameter	Type	Required	Description
`keyword`	`string`	No	Keyword for fuzzy search. If left empty, lists the first 'limit' available fields in their default order.
`limit`	`integer`	No	Maximum number of results
`refresh`	`boolean`	No	Whether to force refresh the field list
Example:

{"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"}

Tip

Use this to discover custom field IDs before using them in jira_create_issue or jira_update_issue.

Get Field Options¶

Get allowed option values for a custom field.

Parameters:

Parameter	Type	Required	Description
`field_id`	`string`	Yes	Custom field ID (e.g., 'customfield_10001'). Use jira_search_fields to find field IDs.
`context_id`	`string`	No	Field context ID (Cloud only). If omitted, auto-resolves to the global context.
`project_key`	`string`	No	Project key (required for Server/DC). Example: 'PROJ'
`issue_type`	`string`	No	Issue type name (required for Server/DC). Example: 'Bug'
`contains`	`string`	No	Case-insensitive substring filter on option values. Also matches child values in cascading selects.
`return_limit`	`integer`	No	Maximum number of results to return (applied after filtering).
`values_only`	`boolean`	No	If true, return only value strings in a compact JSON format instead of full option objects.

Example:

{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}

Tip

Use contains to filter large option lists (e.g., hundreds of values). Combine with values_only: true for a compact response.