> ## Documentation Index
> Fetch the complete documentation index at: https://mcp-atlassian.soomiles.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Jira Search & Fields
> Search issues with JQL, explore fields and field options
### 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. |
| `use_display_names` | `boolean` | No | When true, custom field keys in the output use human-readable display names (e.g. 'Story Points') instead of opaque IDs (e.g. 'customfield\_10243'). The `names` expansion is added automatically. Standard fields are unaffected. Default: false. |
| **Example:** | | | |
```json theme={null}
{"jql": "project = PROJ AND status = 'In Progress' ORDER BY updated DESC", "limit": 20}
```
Always use `ORDER BY` for deterministic results. Use `fields` parameter to limit returned data for faster queries.
Set `use_display_names: true` to get human-readable keys for custom fields instead of opaque IDs like `customfield_XXXXX`.
If a display name conflicts with another output key, that custom field keeps its raw ID so no value is lost.
Some JQL functions (e.g., `issueHistory()`) are Cloud-only.
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:** | | | |
```json theme={null}
{"keyword": "story points", "issue_type": "Story", "project_key": "PROJ"}
```
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:**
```json theme={null}
{"field_id": "customfield_10001", "contains": "high", "return_limit": 5, "values_only": true}
```
Use `contains` to filter large option lists (e.g., hundreds of values). Combine with `values_only: true` for a compact response.
***
### Get Project Issue Types
List the issue types that can be created in a Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | -------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (for example, `PROJ`) |
The response includes each type's ID, name, description, subtask flag, and
untranslated name when Jira provides one.
**Example:**
```json theme={null}
{"project_key": "PROJ"}
```
***
### Get Create Fields
List the fields available when creating one issue type in a Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | -------------------------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (for example, `PROJ`) |
| `issue_type_id` | `string` | Yes | Issue type ID returned by `jira_get_project_issue_types` |
Each field includes its ID, name, required flag, and schema. Use
`jira_get_field_options` to retrieve allowed values for a field.
**Example:**
```json theme={null}
{"project_key": "PROJ", "issue_type_id": "10002"}
```
***