adam-israel/jira-mcp-server

JIRA MCP Server

A Model Context Protocol (MCP) server that integrates JIRA with Cursor AI, allowing you to fetch tickets, identify development tasks, and interact with your JIRA projects directly from your AI chat.

Features

• 🎫 Fetch individual JIRA tickets with full details
• 📋 List your assigned tickets sorted by most recent updates
• 🔍 Search tickets using JQL (JIRA Query Language)
• 📊 List project tickets for any project you have access to
• 🤖 Automatic task identification from ticket descriptions and subtasks
• ✨ Beautiful formatted output optimized for AI interaction

Prerequisites

• Node.js 18+ installed
• A JIRA account with API access
• JIRA API Token (see setup instructions below)

Installation

The server has already been installed and compiled. The directory structure is:

jira-mcp-server/
├── src/
│   └── index.ts          # TypeScript source code
├── dist/
│   └── index.js          # Compiled JavaScript (ready to use)
├── package.json
├── tsconfig.json
└── README.md

Configuration

Step 1: Get Your JIRA API Token

1. Go to https://id.atlassian.com/manage-profile/security/api-tokens
2. Click Create API token
3. Give it a name (e.g., "MCP Server")
4. Copy the token immediately (you won't see it again!)

Step 2: Update MCP Configuration

The MCP configuration file is located at ~/.cursor/mcp.json. Update it with your details:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": [
        "/Users/adamisrael/git-projects/heatwave-dashboard/jira-mcp-server/dist/index.js"
      ],
      "env": {
        "JIRA_HOST": "gieman.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Important: Replace the following placeholders:

• JIRA_EMAIL: Your JIRA account email address
• JIRA_API_TOKEN: The API token you created in Step 1

Step 3: Restart Cursor

After updating mcp.json, you need to restart Cursor for the changes to take effect.

Usage

Once configured and Cursor is restarted, you can use the following tools in your AI chat:

1. Fetch a Specific Ticket

Fetch JIRA ticket AI-MCP-123 and tell me what needs to be done

or

Show me the details of ticket AI-MCP-456

2. List Your Assigned Tickets

Show me all my JIRA tickets

or

What tickets are assigned to me?

3. List Project Tickets

List all tickets in the AI-MCP project

or

Show me recent tickets from project AI-MCP

4. Search with JQL

Search JIRA for tickets with status "In Progress" in project AI-MCP

or

Find all high priority bugs assigned to me

Available Tools

The MCP server exposes the following tools to Cursor:

Read Operations

Write Operations

Development Task Identification

The server automatically analyzes tickets and extracts development tasks from:

1. Subtasks - Parsed and listed with their keys
2. Description bullet points - Extracts numbered or bulleted lists
3. Issue type heuristics - Provides intelligent suggestions based on bug/story/feature classification

Example Workflow

Here's a typical workflow using the JIRA MCP server:

Read Operations

1. List your tickets:

   Show me my JIRA tickets
   

2. Get ticket details:

   Fetch ticket AM-1 and break down the development tasks
   

3. Implement the changes:

   Based on this ticket, update the database schema to add the new user_preferences table
   

4. Search for related work:

   Search JIRA for other tickets mentioning "user preferences" in project AI-MCP
   

Write Operations

5. Add a comment:

   Add this implementation plan as a comment to ticket AM-1
   

6. Update ticket description:

   Update the description of ticket AM-1 with the technical specifications
   

7. Assign a ticket:

   Assign ticket AM-1 to me
   

8. Document progress:

   Add a comment to AM-1: "Completed Phase 1 - Table selection UI implemented"
   

Troubleshooting

Server Not Working

1. Check the logs: Open Cursor's developer console (Help > Toggle Developer Tools)
2. Verify configuration: Ensure mcp.json has the correct paths and credentials
3. Test API token: Try accessing JIRA API directly:

   curl -u your-email@example.com:your-api-token \
     https://gieman.atlassian.net/rest/api/3/myself
   

Authentication Errors

• Verify your email is correct
• Ensure the API token is valid and hasn't expired
• Check that you have access to the JIRA instance

Can't Find Tickets

• Ensure you have the correct project key (e.g., AI-MCP not AIMCP)
• Check that you have permissions to view the tickets
• Verify the ticket exists and you're using the right key format

Security Notes

• Never commit your mcp.json with real credentials to version control
• API tokens should be treated like passwords
• Consider using different tokens for different purposes
• Revoke tokens you're no longer using from the Atlassian management console

Rebuilding After Changes

If you modify the TypeScript source code:

cd /Users/adamisrael/git-projects/heatwave-dashboard/jira-mcp-server
npm run build

Then restart Cursor.

JQL Quick Reference

Some useful JQL queries:

• assignee = currentUser() - Your tickets
• project = AI-MCP - All tickets in a project
• status = "In Progress" - Tickets in progress
• priority = High - High priority tickets
• created >= -7d - Created in last 7 days
• updated >= -1d ORDER BY updated DESC - Updated today

Combine with AND, OR, and parentheses for complex queries.

Support

For issues or questions:

1. Check the Cursor developer console for error messages
2. Verify your JIRA API token is valid
3. Ensure you have proper permissions in JIRA
4. Review the MCP SDK documentation: https://github.com/modelcontextprotocol

License

This MCP server is part of your heatwave-dashboard project and follows the same license.