jira mcp server

A TypeScript-based MCP server that integrates with Jira, allowing Cursor to interact with Jira tickets.

Features

• List Jira tickets
• Get ticket details
• Get ticket comments
• Create new tickets
• Add comments to tickets
• Update ticket status
• Full MCP protocol support for Cursor integration

Setup

1. Install dependencies:

npm install

1. Create a .env file based on .env.example and fill in your Jira credentials:

JIRA_HOST=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token
PORT=3000

To get your Jira API token:

1. Log in to https://id.atlassian.com/manage/api-tokens
2. Click "Create API token"
3. Copy the token and paste it in your .env file

Development

Run the development server:

npm run dev

Build and Run

Build the project:

npm run build

Start the server:

npm start

Cursor Integration

To use this MCP server with Cursor, you have two options:

Option 1: Command-based Integration (Recommended)

1. Build the project:

npm run build

1. Open Cursor's settings:
2. Click on the Cursor menu
3. Select "Settings" (or use the keyboard shortcut)

4. Navigate to the "Extensions" or "Integrations" section

5. Add the MCP configuration:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-mcp-cursor/dist/server.js"]
    }
  }
}

Replace /path/to/jira-mcp-cursor with the absolute path to your project.

Option 2: HTTP-based Integration (Alternative)

1. Start the MCP server (if not already running):

npm start

1. Open Cursor's settings:
2. Click on the Cursor menu
3. Select "Settings" (or use the keyboard shortcut)

4. Navigate to the "Extensions" or "Integrations" section

5. Add the MCP configuration:

{
  "mcpServers": {
    "jira": {
      "url": "http://localhost:3000",
      "capabilities": [
        "list_tickets",
        "get_ticket",
        "get_comments",
        "create_ticket",
        "update_status",
        "add_comment"
      ]
    }
  }
}

Using Jira in Cursor

After configuring the MCP server, you can use Jira commands directly in Cursor:

• /jira list - List your tickets
• /jira view TICKET-123 - View ticket details
• /jira comments TICKET-123 - Get ticket comments
• /jira create - Create a new ticket
• /jira comment TICKET-123 - Add a comment
• /jira status TICKET-123 - Update ticket status

MCP Protocol Support

The server implements the Model-Client-Protocol (MCP) required by Cursor:

• Stdio communication for command-based integration
• Tool registration for Jira operations

API Endpoints

List Tickets

Retrieves a list of Jira tickets, optionally filtered by a JQL query.

Endpoint: GET /api/tickets

Query Parameters:

Example Request:

GET /api/tickets?jql=project=TEST+AND+status=Open

Example Response:

TEST-123: Example ticket (Open)
TEST-124: Another ticket (In Progress)

Get Ticket

Retrieves detailed information about a specific ticket.

Endpoint: GET /api/tickets/:id

Path Parameters:

Example Request:

GET /api/tickets/TEST-123

Example Response:

Key: TEST-123
Summary: Example ticket
Status: Open
Type: Task
Description:
Detailed ticket description

Get Ticket Comments

Retrieves all comments for a specific ticket.

Endpoint: GET /api/tickets/:id/comments

Path Parameters:

Example Request:

GET /api/tickets/TEST-123/comments

Example Response:

[3/20/2024, 10:00:00 AM] John Doe:
Comment text
---

[3/20/2024, 9:30:00 AM] Jane Smith:
Another comment
---

Create Ticket

Creates a new Jira ticket.

Endpoint: POST /api/tickets

Request Body:

Example Request:

POST /api/tickets
Content-Type: application/json

{
  "summary": "New feature request",
  "description": "Implement new functionality",
  "projectKey": "TEST",
  "issueType": "Task"
}

Example Response:

Created ticket: TEST-124

Add Comment

Adds a new comment to an existing ticket.

Endpoint: POST /api/tickets/:id/comments

Path Parameters:

Request Body:

Example Request:

POST /api/tickets/TEST-123/comments
Content-Type: application/json

{
  "body": "This is a new comment"
}

Example Response:

Added comment to TEST-123

Update Status

Updates the status of an existing ticket.

Endpoint: POST /api/tickets/:id/status

Path Parameters:

Request Body:

Example Request:

POST /api/tickets/TEST-123/status
Content-Type: application/json

{
  "transitionId": "21"
}

Example Response:

Updated status of TEST-123

Search Tickets

Searches for tickets across specified projects using text search.

Endpoint: GET /api/tickets/search

Query Parameters:

Example Request:

GET /api/tickets/search?searchText=login+bug&projectKeys=TEST,PROD&maxResults=10

Example Response:

Found 2 tickets matching "login bug"

[TEST] TEST-123: Login page bug
Status: Open (Updated: 3/20/2024, 10:00:00 AM)
Description:
Users unable to login using SSO
----------------------------------------

[PROD] PROD-456: Fix login performance
Status: In Progress (Updated: 3/19/2024, 3:30:00 PM)
Description:
Login page taking too long to load
----------------------------------------