> ## 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 | (Optional) 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. |
| **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. Every issue in the response includes `browse_url`, a direct link to that issue in the Jira web UI.
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.
Cloud supports cursor-based pagination via `page_token` for deterministic results across large datasets. Continue by passing the response's `next_page_token` back as `page_token`; Server/DC uses `start_at` instead.
Some JQL functions (e.g., `issueHistory()`) are Cloud-only.
***
### 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
Get available issue types for a Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ---------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'JTEST') |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ"}
```
The response includes each type's ID, name, description, subtask flag, and untranslated name when Jira provides one.
***
### Get Create Fields
Get fields available for creating an issue of a specific type.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'JTEST') |
| `issue_type_id` | `string` | Yes | The issue type ID (from get\_project\_issue\_types). Example: '10002' for Task. |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ", "issue_type_id": "10002"}
```
Use `jira_get_field_options` to retrieve allowed values for a custom field.
Each field includes its field ID, name, required flag, and schema.
***
### Get Project Fields
Get the fields available on issues of a project (the create schema),
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | -------- | -------- | ----------------------------- |
| `project_key` | `string` | Yes | The project key, e.g. 'PROJ'. |
***
### Search Projects
Search for Jira projects by name or key prefix.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------------- | --------- | -------- | ----------------------------------------------------------- |
| `query` | `string` | Yes | Name or key prefix to search for |
| `max_results` | `integer` | No | Maximum number of results to return |
| `current_project_ids` | `string` | No | Comma-separated list of project IDs to exclude from results |
***