MCP HubMCP Hub
cosmix

jira-mcp

by: cosmix

A Model Context Protocol server for Jira.

18created 10/01/2025
Visit
Jira
Protocol

📌Overview

Purpose: To provide a robust implementation of a Model Context Protocol (MCP) server that facilitates seamless access to JIRA data, enhancing functionalities for AI applications.

Overview: The JIRA MCP Server offers developers an efficient way to interact with JIRA data by tracking relationships, optimizing data transfers, and cleaning content for better AI comprehension. It serves as a bridge between applications and JIRA, enabling advanced data manipulation and retrieval.

Key Features:

  • JQL Search Support: Allows users to search JIRA issues using JQL, returning up to 50 results per request, facilitating quick information retrieval.

  • Epic Children Retrieval: Fetches child issues in an epic along with their comment history and relationship data, limited to 100 issues per request for thorough tracking.

  • Issue Management Capabilities: Enables the creation, updating, and detailed retrieval of JIRA issues, including comments and relationship tracking.

  • Content Cleaning and Transformation: Cleans and transforms JIRA content to maximize its relevance and efficiency for AI applications, ensuring that only essential information is processed.

  • File Attachment Handling: Supports secure multipart uploads for attachments, allowing users to manage files associated with JIRA issues efficiently.

JIRA MCP Server

A Model Context Protocol (MCP) server implementation that provides access to JIRA data with relationship tracking, optimized data payloads, and data cleaning for AI context windows.

ℹ️ There is a separate MCP server for Confluence: https://github.com/cosmix/confluence-mcp

Features

  • Search JIRA issues using JQL (max 50 results per request)
  • Retrieve epic children with comment history and optimized payloads (max 100 issues per request)
  • Get detailed issue information including comments and related issues
  • Create, update, and manage JIRA issues
  • Add comments to issues
  • Extract issue mentions from Atlassian Document Format
  • Track issue relationships (mentions, links, parent/child, epics)
  • Clean and transform rich JIRA content for AI context efficiency
  • Support for file attachments with secure multipart upload handling

Prerequisites

  • Bun (v1.0.0 or higher)
  • JIRA account with API access

Environment Variables

JIRA_API_TOKEN=your_api_token
JIRA_BASE_URL=your_jira_instance_url  # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email

Installation & Setup

1. Clone the repository:

git clone [repository-url]
cd jira-mcp

2. Install dependencies and build:

bun install
bun run build

3. Configure the MCP server:

Edit the appropriate configuration file based on your OS:

macOS:

  • Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

  • Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
  • Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

  • Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
  • Claude Desktop: not available yet

Add the following configuration under the mcpServers object:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email"
      }
    }
  }
}

4. Restart the MCP server

Restart the MCP server within Cline's MCP settings and restart Claude Desktop to load the new MCP server.

Development

Run tests:

bun test

Watch mode for development:

bun run dev

Rebuild after changes:

bun run build

Available MCP Tools

search_issues

Search JIRA issues using JQL. Returns up to 50 results per request.

Input Schema:

{
  searchString: string; // JQL search string
}

get_epic_children

Get all child issues in an epic including comments and relationship data. Limited to 100 issues per request.

Input Schema:

{
  epicKey: string; // The key of the epic issue
}

get_issue

Get detailed information about a specific JIRA issue including comments and all relationships.

Input Schema:

{
  issueId: string; // The ID or key of the JIRA issue
}

create_issue

Create a new JIRA issue with specified fields.

Input Schema:

{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}

update_issue

Update fields of an existing JIRA issue.

Input Schema:

{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}

add_attachment

Add a file attachment to a JIRA issue.

Input Schema:

{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}

add_comment

Add a comment to a JIRA issue. Accepts plain text and converts it internally to Atlassian Document Format.

Input Schema:

{
  issueIdOrKey: string, // The ID or key of the issue
  body: string // The content of the comment (plain text)
}

Data Cleaning Features

  • Extracts text from Atlassian Document Format
  • Tracks issue mentions in descriptions and comments
  • Maintains formal issue links and relationship types
  • Preserves parent/child relationships
  • Tracks epic associations
  • Includes comment history with author info
  • Removes unnecessary metadata from responses
  • Recursively processes content nodes for mentions
  • Deduplicates issue mentions

Technical Details

  • Built with TypeScript (strict mode)
  • Uses Bun runtime for performance
  • Vite for optimized builds
  • Uses JIRA REST API v3
  • Basic authentication with API tokens
  • Batched API requests for related data
  • Optimized payloads for AI context windows
  • Efficient transformation of Atlassian structures
  • Robust error handling
  • Rate limiting considerations
  • Limits:
    • Search results: 50 issues per request
    • Epic children: 100 issues per request
  • Supports multipart form data for secure file attachments
  • Automatic content type detection and validation

Error Handling

  • Network error detection and messaging
  • HTTP status code handling (including 404)
  • Detailed error messages with status codes
  • Console logging of error details
  • Input validation for all parameters
  • Safe error propagation via MCP protocol
  • Specialized handling for common JIRA API errors
  • Base64 validation for attachments
  • Multipart request failure handling
  • Rate limit detection
  • Attachment parameter validation

License

This project is licensed under the MIT License - see the LICENCE file for details.