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:

{"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., ‘[e-mail]’, ‘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:

{"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": "[e-mail]", "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:

{"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:

{"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 or name of the transition to perform (case-insensitive name match, e.g. ‘In Progress’, ‘Done’). Use the jira_get_transitions tool first to see the available transitions for the issue. Example values: ‘11’, ‘21’, ‘31’, ‘In Progress’
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:

{"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)

---