> ## 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 Issues
> Create, read, update, delete, and transition Jira issues
### Get Issue
Get details of a specific Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `fields` | `string` | No | (Optional) Comma-separated list of fields to return (e.g., 'summary,status,customfield\_10010'). You may also provide a single field as a string (e.g., 'duedate'). Use '\*all' for all fields (including custom fields), or omit for essential fields only. |
| `expand` | `string` | No | (Optional) Fields to expand. Examples: 'renderedFields' (for rendered content), 'transitions' (for available status transitions), 'changelog' (for history) |
| `comment_limit` | `integer` | No | Maximum number of comments to include (0 or null for no comments) |
| `properties` | `string` | No | (Optional) A comma-separated list of issue properties to return |
| `update_history` | `boolean` | No | Whether to update the issue view history for the requesting user |
| `include` | `string` | No | (Optional) Comma-separated sections to inline in the response, avoiding extra tool calls. Supported: all, remote\_links, transitions, watchers, changelog, comments, worklogs |
| `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}
{"issue_key": "PROJ-123", "fields": "summary,status,assignee", "comment_limit": 5, "include": "remote_links,transitions"}
```
Use `fields: "*all"` to get all fields including custom ones. Use `expand: "renderedFields"` for rendered HTML content. Use `include: "all"` to inline common enrichments that otherwise require separate tool calls. The response includes `browse_url`, a direct link to the 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.
Custom field IDs differ between Cloud and Server/DC. Use `jira_search_fields` to discover field IDs.
***
### Create Issue
Create a new Jira issue with optional Epic link or parent for subtasks.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------- | -------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `project_key` | `string` | Yes | The JIRA project key (e.g. 'PROJ', 'DEV', 'ACV2'). This is the prefix of issue keys in your project. Never assume what it might be, always ask the user. |
| `summary` | `string` | Yes | Summary/title of the issue |
| `issue_type` | `string` | Yes | Issue type (e.g. 'Task', 'Bug', 'Story', 'Epic', 'Subtask'). The available types depend on your project configuration. For subtasks, use 'Subtask' (not 'Sub-task') and include parent in additional\_fields. |
| `assignee` | `string` | No | (Optional) Assignee's user identifier (string): Email, display name, or account ID (e.g., '[user@example.com](mailto:user@example.com)', 'John Doe', 'accountid:...') |
| `description` | `string` | No | Issue description in Markdown format. On Jira Cloud, use '`{expand:Title}`...`{expand}`' for a collapsible section. |
| `components` | `string` | No | (Optional) Comma-separated list of component names to assign (e.g., 'Frontend,API') |
| `additional_fields` | `string` | No | (Optional) JSON string of additional fields to set. Examples: - Set priority: `{"priority": {"name": "High"}}` - Add labels: `{"labels": ["frontend", "urgent"]}` - Link to parent (for any issue type): `{"parent": "PROJ-123"}` - Link to epic: `{"epicKey": "EPIC-123"}` or `{"epic_link": "EPIC-123"}` - Set Fix Version/s: `{"fixVersions": [{"id": "10020"}]}` - Custom fields: `{"customfield_10010": "value"}` |
| **Example:** | | | |
```json theme={null}
{"project_key": "PROJ", "issue_type": "Task", "summary": "Implement new feature", "description": "## Requirements\n\n- Feature A\n- Feature B"}
```
Use Markdown in the description — it's automatically converted to ADF (Cloud) or wiki markup (Server/DC). On Jira Cloud, mention users with `[~accountid:ACCOUNT_ID]` or `@[Display Name](accountid:ACCOUNT_ID)`. Use `{expand:Title}` and `{expand}` around content to create a collapsible section on Jira Cloud. For epics, provide `epic_name` parameter.
Cloud uses ADF format internally (auto-converted from Markdown). Server/DC uses wiki markup.
***
### Update Issue
Update an issue and optionally transition, comment, and log work.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `fields` | `string` | No | JSON string of fields to update. For 'assignee', provide a string identifier (email, name, or accountId). For 'description', provide text in Markdown format; on Jira Cloud, use '`{expand:Title}`...`{expand}`' for a collapsible section. Example: '`{"assignee": "user@example.com", "summary": "New Summary", "description": "## Updated\nMarkdown text"}`' |
| `additional_fields` | `string` | No | (Optional) JSON string of additional fields to update. Use this for custom fields or more complex updates. Link to epic: `{"epicKey": "EPIC-123"}` or `{"epic_link": "EPIC-123"}`. |
| `components` | `string` | No | (Optional) Comma-separated list of component names (e.g., 'Frontend,API') |
| `attachments` | `string` | No | (Optional) JSON string array or comma-separated list of file paths to attach to the issue. Example: '/path/to/file1.txt,/path/to/file2.txt' or \['/path/to/file1.txt','/path/to/file2.txt'] |
| `transition` | `string` | No | (Optional) Transition name or ID. Transition names are resolved case-insensitively. |
| `comment` | `string` | No | (Optional) Comment text in Markdown format. |
| `comment_visibility` | `string` | No | (Optional) Comment visibility as a JSON string, for example '`{"type":"group","value":"jira-users"}`'. |
| `worklog` | `string` | No | (Optional) Time spent to log, such as '1h 30m'. |
| `worklog_started` | `string` | No | (Optional) ISO datetime when the worklog started. |
| `return_fields` | `string` | No | (Optional) Controls which fields of the updated issue are returned, to reduce response size and token usage. Defaults to '\*all' (the complete issue, which can be very large). TOKEN-SAVING TIP: after an update you usually do NOT need the whole issue back. Pass a comma-separated list of just the field(s) you care about (e.g., 'summary,duedate'), or a single light field such as 'status' for a minimal confirmation - this can cut the response by thousands of tokens. The issue 'key' is always returned regardless. If you later need other fields, fetch them on demand with jira\_get\_issue (which also supports field filtering). Use '\*all' only when you genuinely need the full updated issue. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "fields": "{\"summary\": \"Updated title\", \"description\": \"New description\"}", "transition": "Done", "comment": "Completed the work", "worklog": "1h"}
```
Save response tokens: after an update you rarely need the whole issue back. Set `return_fields` to only the field(s) you changed (e.g., `return_fields: "duedate"`) — this can cut thousands of tokens. Use `*all` only when you need the full updated issue.
`fields` is optional when you only need to transition, comment, or log work. If `transition` and `comment` are both provided, the issue is transitioned first and the comment is added separately afterward. Use `comment_visibility` to restrict the comment's visibility.
Use `additional_fields` as a JSON string for any field not covered by explicit parameters. Find field IDs with `jira_search_fields`.
***
### Delete Issue
Delete an existing Jira issue.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
***
### Assign Issue
Assign a Jira issue to a user using the dedicated assignment endpoint.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `assignee` | `string` | No | User identifier (email, display name, account ID, login name, or JIRAUSER key), or a JSON object string from jira\_search\_assignable\_users. Pass null or empty string to unassign. |
***
### Move Issue to Project
Move a Jira issue to a different project (Jira Cloud only).
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| -------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key to move (e.g., 'PROJ-123') |
| `target_project_key` | `string` | Yes | Key of the target project (e.g., 'OTHERPROJ'). The issue will keep its current issue type and may receive a new key in the target project. |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "target_project_key": "OTHERPROJ"}
```
This tool is only available for Jira Cloud. The target project must support the issue's current type. Jira may assign a new issue key in the target project.
***
### Batch Create Issues
Create multiple Jira issues in a batch.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | --------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issues` | `string` | Yes | JSON array of issue objects. Each object should contain: - project\_key (required): The project key (e.g., 'PROJ') - summary (required): Issue summary/title - issue\_type (required): Type of issue (e.g., 'Task', 'Bug') - description (optional): Issue description in Markdown format - assignee (optional): Assignee username or email - components (optional): Array of component names Example: \[ `{"project_key": "PROJ", "summary": "Issue 1", "issue_type": "Task"}`, `{"project_key": "PROJ", "summary": "Issue 2", "issue_type": "Bug", "components": ["Frontend"]}` ] |
| `validate_only` | `boolean` | No | If true, only validates the issues without creating them |
***
### Transition Issue
Transition a Jira issue to a new status.
This is a **write** tool. Disabled when `READ_ONLY_MODE=true`.
**Parameters:**
| Parameter | Type | Required | Description |
| --------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
| `transition_id` | `string` | Yes | ID of the transition to perform. Use the jira\_get\_transitions tool first to get the available transition IDs for the issue. Example values: '11', '21', '31' |
| `fields` | `string` | No | (Optional) JSON string of fields to update during the transition. Some transitions require specific fields to be set (e.g., resolution). Example: '`{"resolution": {"name": "Fixed"}}`' |
| `comment` | `string` | No | (Optional) Comment to add during the transition in Markdown format. This will be visible in the issue history. Rejected for projects listed in JIRA\_INTERNAL\_ONLY\_PROJECTS (a transition comment may be customer-visible on JSM and cannot be forced internal): transition without a comment, then post an internal note with jira\_add\_comment(public=false). |
| **Example:** | | | |
```json theme={null}
{"issue_key": "PROJ-123", "transition_name": "Done", "comment": "Closing as completed"}
```
Use `jira_get_transitions` first to see available transitions for the current issue state.
***
### Get Transitions
Get available status transitions for a Jira issue.
**Parameters:**
| Parameter | Type | Required | Description |
| ----------- | -------- | -------- | --------------------------------------------- |
| `issue_key` | `string` | Yes | Jira issue key (e.g., 'PROJ-123', 'ACV2-642') |
***
### Get All Projects
Get all Jira projects accessible to the current user.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------------ | --------- | -------- | --------------------------------------------------- |
| `include_archived` | `boolean` | No | Whether to include archived projects in the results |
***
### Get Project Issues
Get all issues for a specific Jira project.
**Parameters:**
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | --------------------------------------- |
| `project_key` | `string` | Yes | Jira project key (e.g., 'PROJ', 'ACV2') |
| `limit` | `integer` | No | Maximum number of results (1-50) |
| `start_at` | `integer` | No | Starting index for pagination (0-based) |
***