JIRA MCP Server

A Model Context Protocol (MCP) server that provides JIRA integration capabilities. This server allows AI assistants to search, view, create, and update JIRA issues using natural language.

Features

• Search Issues: Search for JIRA issues using JQL (JIRA Query Language)

• Get Issue Details: Retrieve detailed information about specific issues

• Create Issues: Create new JIRA issues with customizable fields

• Update Issues: Update existing issues including status transitions

Installation

Configuration

The server requires three environment variables:

• JIRA_URL: Your JIRA instance URL (e.g., https://your-domain.atlassian.net)

• JIRA_EMAIL: Your JIRA account email

• JIRA_API_TOKEN: Your JIRA API token

Getting a JIRA API Token

1. Log in to https://id.atlassian.com/manage-profile/security/api-tokens

2. Click "Create API token"

3. Give it a label and copy the token

Setup for Claude Desktop

The server supports both stdio and SSE transport modes. For Claude Desktop and other MCP clients that spawn processes, stdio mode is used automatically.

Add this to your Claude Desktop configuration file:

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

Alternatively, if running locally:

The server will automatically detect that it's being run by an MCP client (stdin is not a TTY) and use stdio transport mode.

Available Resources

The MCP server exposes JIRA data as resources that can be listed and read:

jira://search?jql={query}

Search for JIRA issues using JQL queries.

Example URIs:

• jira://search?jql=project=ST AND status=Open

• jira://search?jql=project=ST AND type=Task AND component in (BuildReq, ValidationReq) AND status=Open ORDER BY priority DESC

• jira://search?jql=assignee=currentUser() AND status!=Done

jira://issue/{issueKey}

Get detailed information about a specific issue.

Example URIs:

• jira://issue/ST-123

• jira://issue/PROJ-456

Available Tools

jira_search

Search for JIRA issues using JQL.

Parameters:

• jql (required): JQL query string

• maxResults (optional): Maximum results to return (default: 50)

• startAt (optional): Starting index for pagination (default: 0)

• fields (optional): Array of field names to return

Example:

jira_get_issue

Get detailed information about a specific issue.

Parameters:

• issueKey (required): Issue key (e.g., "PROJ-123")

• fields (optional): Array of field names to return

Example:

jira_create_issue

Create a new JIRA issue.

Parameters:

• projectKey (required): Project key

• summary (required): Issue title

• issueType (required): Issue type (e.g., "Task", "Bug", "Story")

• description (optional): Issue description

• priority (optional): Priority level

• assignee (optional): Assignee account ID

• labels (optional): Array of labels

Example:

jira_update_issue

Update an existing JIRA issue.

Parameters:

• issueKey (required): Issue key to update

• summary (optional): New summary

• description (optional): New description

• priority (optional): New priority

• assignee (optional): New assignee account ID

• labels (optional): New labels array

• status (optional): New status (triggers transition)

Example:

Usage Examples

After configuring the server in Claude Desktop, you can use natural language commands like:

• "Search for all issues in the PROJ project that are in progress"

• "Show me details for issue PROJ-123"

• "Create a new task in PROJ with title 'Update documentation'"

• "Update PROJ-456 and set its status to Done"

Transport Modes

The server supports two transport modes:

Stdio Mode (Default for MCP Clients)

When the server is spawned by an MCP client (like Claude Desktop), it automatically detects that stdin is not a TTY and uses stdio transport. This is the standard mode for local MCP integrations.

You can also explicitly force stdio mode by setting:

SSE Mode (HTTP Server)

The server can also run as an HTTP server using Server-Sent Events (SSE) transport. This allows it to be used by any MCP client that supports SSE connections over HTTP.

Start the Server in SSE Mode

To start the server in SSE mode (HTTP server), set the PORT environment variable:

Or explicitly set the transport mode:

The server will automatically use SSE mode if:

• PORT environment variable is set

• MCP_TRANSPORT=sse is set

• stdin is a TTY (running interactively)

SSE Endpoints

Once running, the server exposes:

• SSE Connection: GET http://localhost:3000/sse - Main SSE endpoint for MCP communication

• Message Endpoint: POST http://localhost:3000/message - Endpoint for sending messages to the server

• Health Check: GET http://localhost:3000/health - Server health status

Connecting MCP Clients

To connect an MCP client to the SSE server, use the SSE endpoint URL:

Testing the Server

You can test if the server is running:

Development

The server follows the Model Context Protocol specification and supports both stdio and SSE transports:

• Stdio transport: For local MCP clients that spawn processes (e.g., Claude Desktop)

• SSE transport: For HTTP-based MCP clients and web applications

The transport mode is automatically detected based on the execution context, but can be explicitly controlled via the MCP_TRANSPORT environment variable (stdio or sse).

License

MIT