JIRA Cloud MCP Server

A Model Context Protocol (MCP) server for seamless integration with JIRA Cloud. This server enables AI assistants like Claude to interact with JIRA Cloud, providing comprehensive issue management, status tracking, and analytics capabilities.

Table of Contents

• Features
• Prerequisites
• Configuration
  • Getting Your JIRA API Token
• Usage with Claude Desktop
• Available Tools
  • jira_search_issues
  • jira_get_issue
  • jira_create_issue
  • jira_update_issue
  • jira_get_transitions
  • jira_transition_issue
  • jira_get_changelog
  • jira_list_projects
  • jira_get_project
  • jira_add_comment
  • jira_get_comments
  • jira_update_comment
  • jira_delete_comment
  • jira_get_issue_link_types
  • jira_get_field_options
  • jira_delete_issue
  • jira_search_users
• JQL Query Examples
• Troubleshooting
  • Authentication Failed
  • Permission Denied
  • Rate Limiting
  • Issue Not Found
  • Invalid JQL
• Security Notes
• JIRA Cloud vs JIRA Server/Data Center
• Resources

Features

• Issue Management: Search, create, read, and update JIRA issues
• Status Management: View available transitions and update issue status
• History Tracking: Access complete status history with time-in-status analytics
• Project Operations: List projects and get issue types
• Comments: Add and retrieve comments from issues with pagination
• Labels: Apply labels when creating issues
• JQL Support: Full JIRA Query Language support for advanced searching
• API Token Authentication: Secure authentication using JIRA Cloud API tokens

Prerequisites

• Node.js 18 or higher - Required to run the MCP server
• JIRA Cloud account with appropriate permissions
• JIRA Cloud API token (see Configuration section below)

Configuration

Getting Your JIRA API Token

1. Log in to your Atlassian account at https://id.atlassian.com
2. Go to Security → API tokens
3. Click Create API token
4. Give it a descriptive name (e.g., "MCP Server")
5. Copy the generated token immediately (you won't be able to see it again)

Usage with Claude Desktop

Edit your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "jira-cloud": {
      "command": "npx",
      "args": ["mcp-server-jira-cloud"],
      "env": {
        "JIRA_BASE_URL": "https://yourcompany.atlassian.net",
        "JIRA_EMAIL": "[email protected]",
        "JIRA_API_TOKEN": "your_api_token_here"
      }
    }
  }
}

Replace the environment variables with your actual JIRA Cloud URL, email, and API token.

Restart Claude Desktop

After saving the configuration, restart Claude Desktop for the changes to take effect.

Available Tools

1. jira_search_issues

Search for JIRA issues using JQL (JIRA Query Language).

Parameters:

• jql (required): JQL query string
• maxResults (optional): Maximum results to return (default: 50, max: 5000, recommended: 50-100)
• nextPageToken (optional): Token for pagination (obtained from previous search response)
• fields (optional): Specific fields to return

Pagination: This tool uses JIRA's new token-based pagination. The response includes:

• issues: Array of matching issues
• nextPageToken: Token to fetch the next page (if more results exist)
• isLast: Boolean indicating if this is the last page

To paginate through results, use the nextPageToken from the previous response in your next search request.

Example queries to ask Claude:

• "Search for all open bugs in project ABC"
• "Find all issues assigned to me that are in progress"
• "Show me high priority tasks created in the last week"
• "Get the next page of results using this token: xyz123"

2. jira_get_issue

Get detailed information about a specific JIRA issue.

Parameters:

• issueKey (required): Issue key (e.g., PROJ-123)
• expand (optional): Additional data to expand (e.g., changelog, transitions)
• fields (optional): Specific fields to return (reduces response size and context usage)

Default Behavior (Optimized):

When the fields parameter is omitted, this tool returns a curated set of commonly needed fields:

• summary
• issuetype
• status
• priority
• labels
• description
• assignee
• reporter
• created
• updated
• resolution
• issuelinks
• timeestimate
• timeremaining
• duedate
• components
• fixVersions

This default set excludes large fields like comments, attachments, and worklogs to optimize context usage.

Custom Field Selection:

Use the fields parameter to customize what data is returned:

Field patterns:

• Specific fields: ["summary", "status", "priority"]
• All except comments: ["*all", "-comment"]
• Navigable fields only: ["*navigable"]
• All fields: ["*all"]

Example queries:

• "Get details for issue PROJ-123" (returns optimized default fields)
• "Get PROJ-123 with summary, status, and priority fields" (specify a minimal field list)
• "Show me all fields for ABC-456 including comments" (use ["*all"])

3. jira_create_issue

Create a new JIRA issue with labels and custom fields.

Parameters:

• projectKey (required): Project key
• issueType (required): Issue type (e.g., Bug, Story, Task)
• summary (required): Issue summary/title
• description (optional): Issue description
• labels (optional): Array of labels
• assignee (optional): Assignee account ID
• priority (optional): Priority name (e.g., High, Medium, Low)
• customFields (optional): Custom fields as key-value pairs

Example queries:

• "Create a new bug in project ABC with title 'Login page crashes' and label 'frontend'"
• "Create a high priority task in PROJ: 'Update documentation' assigned to John"

4. jira_update_issue

Update an existing JIRA issue.

Parameters:

• issueKey (required): Issue key to update
• summary (optional): New summary
• description (optional): New description
• labels (optional): Labels (replaces existing)
• assignee (optional): Assignee account ID
• priority (optional): Priority name
• customFields (optional): Custom fields to update

Example queries:

• "Update PROJ-123 to change its priority to High"
• "Add label 'urgent' to issue ABC-456"
• "Assign issue PROJ-123 to user with account ID 5b10a2844c20165700ede21g"
• "Unassign issue ABC-456"

Assigning Issues:

This tool supports assigning and unassigning issues:

To assign an issue:

• Use the assignee parameter with the user's account ID
• Example: { "issueKey": "PROJ-123", "assignee": "5b10a2844c20165700ede21g" }

To unassign an issue:

• Use the assignee parameter with null or an empty string
• Example: { "issueKey": "PROJ-123", "assignee": null }

Note: You need the user's account ID, not their email or display name. Account IDs can be found using the JIRA web interface or by implementing the jira_search_users tool (see future-tools.md).

5. jira_get_transitions

Get available status transitions for a JIRA issue.

Parameters:

• issueKey (required): Issue key

Example queries:

• "What status transitions are available for PROJ-123?"
• "Show me the possible next states for issue ABC-456"

6. jira_transition_issue

Transition a JIRA issue to a new status.

Parameters:

• issueKey (required): Issue key
• transitionId (required): Transition ID (get from jira_get_transitions)
• comment (optional): Comment to add with transition

Example queries:

• "Move PROJ-123 to 'In Progress'"
• "Mark ABC-456 as Done with comment 'Completed and tested'"

7. jira_get_changelog

Get complete changelog for an issue with time-in-status analytics.

Parameters:

• issueKey (required): Issue key
• includeTimeInStatus (optional): Calculate time spent in each status (default: true)

Example queries:

• "Show me the complete history of PROJ-123"
• "How long has ABC-456 been in each status?"
• "Analyze the time-in-status for issue XYZ-789"

8. jira_list_projects

List all accessible JIRA projects.

Parameters:

• startAt (optional): Starting index for pagination (default: 0)
• maxResults (optional): Maximum results (default: 50)

Example queries:

• "List all JIRA projects"
• "Show me the available projects"

9. jira_get_project

Get detailed information about a specific project including issue types.

Parameters:

• projectKey (required): Project key

Example queries:

• "Get details for project ABC"
• "What issue types are available in project PROJ?"

10. jira_add_comment

Add a comment to a JIRA issue.

Parameters:

• issueKey (required): Issue key
• body (required): Comment text

Example queries:

• "Add a comment to PROJ-123: 'This needs review'"
• "Comment on ABC-456 that the fix is ready for testing"

11. jira_get_comments

Get comments from a JIRA issue with pagination.

Parameters:

• issueKey (required): Issue key
• startAt (optional): Starting index for pagination (default: 0)
• maxResults (optional): Maximum comments (default: 50)
• orderBy (optional): Sort order ('created' or '-created')

Example queries:

• "Show me all comments on PROJ-123"
• "Get the latest comments from issue ABC-456"

12. jira_update_comment

Update an existing comment on a JIRA issue.

Parameters:

• issueKey (required): Issue key
• commentId (required): Comment ID to update
• body (required): Updated comment text

Example queries:

• "Update comment 10000 on issue PROJ-123 with text 'Corrected information'"
• "Edit comment 10001 on ABC-456 to say 'This has been resolved'"

Note: You can get comment IDs from the jira_get_comments tool.

13. jira_delete_comment

Delete a comment from a JIRA issue.

Parameters:

• issueKey (required): Issue key
• commentId (required): Comment ID to delete

Example queries:

• "Delete comment 10000 from issue PROJ-123"
• "Remove comment 10001 from ABC-456"

Note:

• Deleted comments cannot be recovered
• You need either "Delete all comments" permission or "Delete own comments" permission (if you're the comment author)
• You can get comment IDs from the jira_get_comments tool

14. jira_get_issue_link_types

Get all available issue link types in your JIRA instance.

Parameters:

• None

Returns:

• issueLinkTypes: Array of link type objects, each containing:
  • id: Unique identifier for the link type
  • name: Display name (e.g., "Blocks", "Clones", "Relates")
  • inward: Description for the inward relationship (e.g., "is blocked by")
  • outward: Description for the outward relationship (e.g., "blocks")
  • self: API URL for this link type

Example queries:

• "What issue link types are available?"
• "Show me all relationship types I can use for linking issues"
• "List the available issue link types"

Use cases:

• Discovering available relationship types before creating issue links
• Building UI for issue linking features
• Understanding the link types configured in your JIRA instance

Common link types:

• Blocks/Blocked by - Indicates dependency relationships
• Clones/Cloned by - For duplicate or cloned issues
• Duplicate/Duplicated by - For marking duplicate issues
• Relates to - General relationship between issues

Note: This endpoint can be accessed anonymously and doesn't require special permissions.

15. jira_get_field_options

Get field metadata for creating issues in a specific project and issue type. This returns valid values for all fields including priorities (respecting priority schemes), assignees, components, versions, and other field constraints.

Parameters:

• projectKey (required): Project key (e.g., "PROJ")
• issueTypeId (required): Issue type ID (get from jira_get_project)

Returns: Field metadata object containing:

• fields: Object with metadata for each field
  • Each field includes:
    • required: Boolean indicating if field is required
    • schema: Field type information
    • name: Display name
    • operations: Allowed operations (e.g., "set")
    • allowedValues: Array of valid values (for select fields)

Priority-Specific Usage: To get valid priorities for a project/issue type:

// Extract priorities from response
const priorities = response.fields.priority.allowedValues;
// Returns array of: [{id, name, description, iconUrl, statusColor}, ...]

Example queries:

• "What priorities are available for creating bugs in project PROJ?"
• "Show me all valid field values for creating a Task in ABC project"
• "What are the required fields for creating a Story in PROJ?"
• "Get the issue type ID from ABC project, then show me create metadata for that type"

Use cases:

• Context-aware priority discovery - Get ONLY priorities valid for specific project/issue type (respects priority schemes)
• Form validation - Validate field values before creating issues
• Dynamic UI generation - Populate dropdowns with correct options
• Required field detection - Identify which fields are mandatory
• Custom field discovery - Find available custom fields and their constraints
• Assignee validation - Get list of users who can be assigned to issues

Understanding Priority Schemes:

JIRA Cloud uses priority schemes to control which priorities are available in each project:

• Different projects can have different sets of available priorities
• This tool returns ONLY priorities valid for the specific project/issue type (respects priority schemes)
• Always use this tool when you need to discover valid priorities for a project

Example Response Structure:

{
  "fields": {
    "priority": {
      "required": false,
      "schema": {
        "type": "priority",
        "system": "priority"
      },
      "name": "Priority",
      "operations": ["set"],
      "allowedValues": [
        {
          "id": "1",
          "name": "Highest",
          "iconUrl": "https://...",
          "description": "Critical issues..."
        },
        {
          "id": "3",
          "name": "Medium",
          "iconUrl": "https://..."
        }
      ]
    },
    "summary": {
      "required": true,
      "schema": {
        "type": "string",
        "system": "summary"
      },
      "name": "Summary",
      "operations": ["set"]
    }
  }
}

Permissions Required:

• Browse projects project permission
• Create issues project permission

Note:

• This is the recommended way to discover valid field values before creating issues
• Respects project-specific priority schemes (only shows priorities available for the context)
• Returns metadata for ALL fields, not just priorities
• Use jira_get_project to get available issue type IDs for a project

16. jira_delete_issue

Delete a JIRA issue permanently.

Parameters:

• issueKey (required): Issue key to delete (e.g., "PROJ-123")
• deleteSubtasks (optional): Delete all subtasks as well (default: false)

Example queries:

• "Delete issue PROJ-123"
• "Delete issue ABC-456 and all its subtasks"
• "Remove test issue TEST-999"

Use cases:

• Removing test issues from a project
• Cleaning up duplicate issues
• Deleting issues as part of project cleanup
• Removing invalid or spam issues

⚠️ CRITICAL WARNINGS:

1. IRREVERSIBLE OPERATION - Deleted issues CANNOT be recovered through the API or JIRA interface
2. Subtask handling - The API will reject deletion if the issue has subtasks unless deleteSubtasks is set to true
3. Audit trail loss - Consider transitioning issues to a "Closed" or "Done" status instead of deleting them to maintain audit trails
4. Issue links broken - All links to/from the deleted issue will be broken
5. History lost - All comments, attachments, and change history will be permanently deleted

Permissions Required:

• Browse projects project permission
• Delete issues project permission
• If issue-level security is configured: issue-level security permission to view the issue

Error Cases:

• 400 Bad Request: Issue has subtasks but deleteSubtasks is false
• 403 Forbidden: User does not have permission to delete the issue
• 404 Not Found: Issue does not exist or user cannot view it

Best Practice: Instead of deleting issues, consider:

• Transitioning to a closed status (preserves audit trail)
• Moving to an archive project (keeps data accessible)
• Adding labels like "duplicate" or "invalid" (maintains searchability)

Note: This operation can be accessed anonymously if JIRA permissions allow it.

17. jira_search_users

Search for users in JIRA by query string. Returns user details including account IDs needed for assignment and other operations.

Parameters:

• query (optional): Search by partial email address, display name, or username
• accountId (optional): Filter by specific account ID
• startAt (optional): Starting index for pagination (default: 0)
• maxResults (optional): Maximum number of results to return (default: 50, max: 1000)

Example queries:

• "Search for users with email [email protected]"
• "Find user with display name John Doe"
• "Look up user with account ID 5b10a2844c20165700ede21g"
• "Search for users matching 'smith'"

Use cases:

• Finding account IDs to assign issues to users
• Looking up users before performing operations
• User autocomplete functionality
• Validating user existence before creating assignments
• Building user selection lists

Response includes:

• accountId: User's account ID (needed for assignment)
• displayName: User's full name
• emailAddress: User's email (if permissions allow)
• active: Whether the user account is active
• avatarUrls: URLs to user's avatar images
• accountType: Type of account (e.g., "atlassian")
• timeZone: User's configured timezone
• locale: User's locale settings

Examples:

// Search by email
{
  "query": "[email protected]"
}

// Search by display name
{
  "query": "John Doe"
}

// Get specific user by account ID
{
  "accountId": "5b10a2844c20165700ede21g"
}

// Paginated search
{
  "query": "smith",
  "startAt": 0,
  "maxResults": 50
}

Permissions Required:

• Browse users global permission
• Administer JIRA global permission (to get users for any project)
• OR Administer Projects project permission (to get users for that specific project)

Important Notes:

• The username parameter has been deprecated due to privacy changes; use query instead
• Results are paginated with a maximum of 1000 results per request
• Email addresses may not be returned if privacy settings restrict access
• Customer accounts in JSM may have different accountId formats (e.g., qm:...)
• Use the returned accountId for assignment operations with jira_update_issue

Common workflow:

1. Search for a user: jira_search_users with query parameter
2. Get the user's accountId from the results
3. Assign an issue: Use jira_update_issue with the assignee parameter set to the accountId

JQL Query Examples

JIRA Query Language (JQL) is a powerful way to search for issues. Here are some common examples:

# All open issues in a project
project = ABC AND status != Done

# Issues assigned to you
assignee = currentUser()

# High priority bugs
type = Bug AND priority = High

# Issues created in the last 7 days
created >= -7d

# Issues updated today
updated >= startOfDay()

# Complex query with multiple conditions
project = ABC AND status = "In Progress" AND assignee = currentUser() AND priority IN (High, Highest)

# Issues with specific labels
labels = frontend AND labels = urgent

# Issues without assignee
assignee is EMPTY

Troubleshooting

Authentication Failed

Error: "Authentication failed. Please check your email and API token."

Solution:

1. Verify your email address is correct
2. Generate a new API token from https://id.atlassian.com/manage-profile/security/api-tokens
3. Make sure you're using the correct JIRA Cloud URL (not Server/Data Center)

Permission Denied

Error: "Forbidden - You do not have permission to access this resource."

Solution:

• Check that your JIRA account has the necessary permissions for the operation
• Some operations require project admin or JIRA admin permissions
• Contact your JIRA administrator if you need additional permissions

Rate Limiting

Error: "Rate limit exceeded. Please try again later."

Solution:

• JIRA Cloud has rate limits that vary by plan
• Wait a few minutes before retrying
• Consider reducing the frequency of requests

Issue Not Found

Error: "Not Found - The requested resource does not exist."

Solution:

• Verify the issue key is correct (e.g., PROJ-123, not proj-123)
• Check that you have permission to view the issue
• Ensure the issue exists in your JIRA instance

Invalid JQL

Error: "Bad Request - [JQL error message]"

Solution:

• Review your JQL syntax
• Use the JIRA web interface to test your query first
• Refer to the JQL documentation: https://support.atlassian.com/jira-software-cloud/docs/use-advanced-search-with-jira-query-language-jql/

Security Notes

• API tokens have the same permissions as your user account
• Rotate API tokens regularly
• Monitor API token usage in your Atlassian account settings

JIRA Cloud vs JIRA Server/Data Center

This server is designed specifically for JIRA Cloud. Key differences:

| Feature | JIRA Cloud | JIRA Server/Data Center | |---------|------------|-------------------------| | Authentication | API Token + Email | Personal Access Token or Username + Password | | API Version | REST API v3 | REST API v2 | | Base URL | https://company.atlassian.net | Self-hosted URL |

If you're using JIRA Server or Data Center, you'll need a different implementation.

Resources

• JIRA Cloud REST API Documentation
• JQL Documentation
• Model Context Protocol Documentation
• Atlassian API Tokens