mcp-jira

✨ Features

• 🎯 Complete JIRA Integration Suite

• 🏗️ Enterprise-Grade Architecture _(New in v0.5.0)_

• 🔍 Powerful Search & Discovery

• 📝 Advanced Issue Management
  • Create, update, and transition issues with comprehensive field support
  • Time tracking, worklog management, and custom field support
  • ADF (Atlassian Document Format) parsing for rich content display
  • Array operations for labels, components, and versions

🆕 What's New in v0.5.0

🏗️ Major Architecture Overhaul

• Complete code reorganization with modular, domain-driven architecture
• HTTP client refactoring with dedicated utility classes for improved reliability
• Critical bug fix for malformed JIRA API URLs that prevented proper communication

🧪 Enhanced Testing & Quality

• 95+ new tests added for HTTP client utilities and edge cases
• 822 total tests ensuring comprehensive coverage and stability
• Zero linting warnings with enhanced Biome integration

🔧 Technical Improvements

• Enhanced error handling with better classification and actionable messages
• Improved logging with structured debug information and performance monitoring
• Type safety enhancements with strict TypeScript checking throughout

🚀 Performance & Reliability

• Optimized HTTP requests with better connection management
• Enhanced error recovery with improved retry logic and timeout handling
• Backward compatibility maintained - seamless upgrade from v0.4.x

🚀 Quick Start

Installation

Add this configuration to your MCP client:

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-jira@latest"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "your-email@example.com",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Development Setup

For local development and testing:

# Clone the repository
git clone https://github.com/Dsazz/mcp-jira.git
cd mcp-jira

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your JIRA credentials

# Build the project
bun run build

# Test with MCP Inspector
bun run inspect

Configuration

Create a `.env` file with the following variables:

JIRA_HOST=https://your-instance.atlassian.net
JIRA_USERNAME=your-email@example.com
JIRA_API_TOKEN=your-jira-api-token-here

> 🔑 Important Note About JIRA API Tokens

>

> - A JIRA API token can be generated at Atlassian API Tokens

> - Tokens may contain special characters, including the `=` sign

> - Place the token on a single line in the `.env` file

> - Do not add quotes around the token value

> - Paste the token exactly as provided by Atlassian

🧰 Available Tools

Core JIRA Tools

Issue Creation Parameters

The `jira_create_issue` tool supports comprehensive issue creation:

Required:

• `projectKey`: String - Project key (e.g., `"PROJ"`)
• `issueType`: String - Issue type (e.g., `"Task"`, `"Bug"`, `"Story"`)
• `summary`: String - Issue title/summary

Optional Fields:

• `description`: String - Detailed description (supports ADF format)
• `priority`: String - Priority level (`"Highest"`, `"High"`, `"Medium"`, `"Low"`, `"Lowest"`)
• `assignee`: String - Assignee username or email
• `reporter`: String - Reporter username or email
• `labels`: Array - Labels to apply to the issue
• `components`: Array - Component names
• `fixVersions`: Array - Fix version names
• `affectsVersions`: Array - Affected version names
• `timeEstimate`: String - Time estimate in JIRA format (e.g., `"2h"`, `"1d 4h"`)
• `dueDate`: String - Due date in ISO format
• `environment`: String - Environment description
• `customFields`: Object - Custom field values

Examples:

# Basic issue creation
jira_create_issue projectKey:"PROJ" issueType:"Task" summary:"Fix login bug"

# Comprehensive issue with all fields
jira_create_issue projectKey:"PROJ" issueType:"Bug" summary:"Critical login issue" description:"Users cannot log in" priority:"High" assignee:"john.doe" labels:["urgent","security"] timeEstimate:"4h"

Issue Update Parameters

The `jira_update_issue` tool supports comprehensive issue updates:

Required:

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

Field Updates (any combination):

• `summary`: String - Update issue title
• `description`: String - Update description
• `priority`: String - Change priority
• `assignee`: String - Reassign issue
• `reporter`: String - Change reporter
• `timeEstimate`: String - Update time estimate
• `timeSpent`: String - Log time spent
• `dueDate`: String - Update due date
• `environment`: String - Update environment

Array Operations (add/remove/set):

• `labels`: Object - Modify labels (`{operation: "add|remove|set", values: ["label1", "label2"]}`)
• `components`: Object - Modify components
• `fixVersions`: Object - Modify fix versions
• `affectsVersions`: Object - Modify affected versions

Status Transitions:

• `status`: String - Transition to new status (e.g., `"In Progress"`, `"Done"`)

Worklog:

• `worklog`: Object - Add work log entry (`{timeSpent: "2h", comment: "Fixed issue"}`)

Examples:

# Update basic fields
jira_update_issue issueKey:"PROJ-123" summary:"Updated title" priority:"High"

# Add labels and transition status
jira_update_issue issueKey:"PROJ-123" labels:'{operation:"add",values:["urgent"]}' status:"In Progress"

# Log work and add comment
jira_update_issue issueKey:"PROJ-123" worklog:'{timeSpent:"2h",comment:"Completed testing"}'

Project Parameters

The `jira_get_projects` tool supports project discovery:

Optional Parameters:

• `maxResults`: Number (1-100, default: 50) - Limit number of results
• `startAt`: Number (default: 0) - Pagination offset
• `expand`: Array - Additional fields to include (`["description", "lead", "issueTypes", "url", "projectKeys"]`)

Examples:

# Get all projects
jira_get_projects

# Get projects with additional details
jira_get_projects expand:["description","lead","issueTypes"] maxResults:20

Board Parameters

The `jira_get_boards` tool supports board management:

Optional Parameters:

• `maxResults`: Number (1-100, default: 50) - Limit number of results
• `startAt`: Number (default: 0) - Pagination offset
• `type`: String - Board type (`"scrum"`, `"kanban"`)
• `name`: String - Filter by board name
• `projectKeyOrId`: String - Filter by project

Examples:

# Get all boards
jira_get_boards

# Get Scrum boards for specific project
jira_get_boards type:"scrum" projectKeyOrId:"PROJ"

# Search boards by name
jira_get_boards name:"Sprint Board" maxResults:10

Sprint Parameters

The `jira_get_sprints` tool supports sprint management:

Required:

• `boardId`: Number - Board ID to get sprints from

Optional Parameters:

• `maxResults`: Number (1-100, default: 50) - Limit number of results
• `startAt`: Number (default: 0) - Pagination offset
• `state`: String - Sprint state (`"active"`, `"closed"`, `"future"`)

Examples:

# Get all sprints for a board
jira_get_sprints boardId:123

# Get only active sprints
jira_get_sprints boardId:123 state:"active"

# Get sprints with pagination
jira_get_sprints boardId:123 maxResults:10 startAt:20

Worklog Parameters

The worklog tools support comprehensive time tracking:

`jira_add_worklog` Parameters:

Required:

• `issueKey`: String - Issue key (e.g., `"PROJ-123"`)
• `timeSpent`: String - Time spent in JIRA format (e.g., `"2h"`, `"1d 4h"`, `"30m"`)

Optional:

• `comment`: String - Comment describing the work done
• `started`: String - When work started (ISO date format, defaults to now)
• `visibility`: Object - Visibility settings (`{type: "group", value: "jira-developers"}`)

`jira_get_worklogs` Parameters:

Required:

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

Optional:

• `startedAfter`: String - Filter worklogs started after this date (ISO format)
• `startedBefore`: String - Filter worklogs started before this date (ISO format)

`jira_update_worklog` Parameters:

Required:

• `issueKey`: String - Issue key (e.g., `"PROJ-123"`)
• `worklogId`: String - Worklog ID to update

Optional (any combination):

• `timeSpent`: String - Update time spent
• `comment`: String - Update comment
• `started`: String - Update start time

`jira_delete_worklog` Parameters:

Required:

• `issueKey`: String - Issue key (e.g., `"PROJ-123"`)
• `worklogId`: String - Worklog ID to delete

Examples:

# Add worklog entry
jira_add_worklog issueKey:"PROJ-123" timeSpent:"2h" comment:"Fixed authentication bug"

# Get all worklogs for an issue
jira_get_worklogs issueKey:"PROJ-123"

# Get worklogs from last week
jira_get_worklogs issueKey:"PROJ-123" startedAfter:"2025-05-29T00:00:00.000Z"

# Update worklog
jira_update_worklog issueKey:"PROJ-123" worklogId:"12345" timeSpent:"3h" comment:"Updated work description"

# Delete worklog
jira_delete_worklog issueKey:"PROJ-123" worklogId:"12345"

Comment Parameters

The `jira_get_issue_comments` tool supports progressive disclosure with these parameters:

Required:

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

Basic Options:

• `maxComments`: Number (1-100, default: 10) - Maximum number of comments to retrieve
• `orderBy`: String (`"created"` or `"updated"`, default: `"created"`) - Sort order for comments

Advanced Options:

• `includeInternal`: Boolean (default: false) - Include internal/restricted comments
• `authorFilter`: String - Filter comments by author name or email
• `dateRange`: Object - Filter by date range:
  • `from`: String (ISO date) - Start date
  • `to`: String (ISO date) - End date

Examples:

# Basic usage - get 10 most recent comments
jira_get_issue_comments PROJ-123

# Get more comments with specific ordering
jira_get_issue_comments PROJ-123 maxComments:25 orderBy:"updated"

# Advanced filtering
jira_get_issue_comments PROJ-123 authorFilter:"john.doe" includeInternal:true

Search Parameters

The `search_jira_issues` tool supports two modes:

Expert Mode (JQL):

• `jql`: Direct JQL query string (e.g., `"project = PROJ AND status = Open"`)

Beginner Mode (Helper Parameters):

• `assignedToMe`: Boolean - Show only issues assigned to current user
• `project`: String - Filter by project key
• `status`: String or Array - Filter by status(es) (e.g., `"Open"` or `["Open", "In Progress"]`)
• `text`: String - Search in summary and description fields

Common Options:

• `maxResults`: Number (1-50, default: 25) - Limit number of results
• `fields`: Array - Specify which fields to retrieve (optional)

🛠️ Development Tools

Code Quality Tools

The project uses Biome for code formatting and linting, providing:

• Fast, unified formatting and linting
• TypeScript-first tooling
• Zero configuration needed
• Consistent code style enforcement

# Format code
bun run format

# Check code for issues
bun run check

# Type check
bun run typecheck

# Run tests
bun test

MCP Inspector

Click to expand MCP Inspector details

The MCP Inspector is a powerful tool for testing and debugging your MCP server.

# Run the inspector (no separate build step needed)
bun run inspect

The inspector automatically:

• Loads environment variables from `.env`
• Cleans up occupied ports (5175, 3002)
• Builds the project when needed
• Starts the MCP server with your configuration
• Launches the inspector UI

Visit the inspector at http://localhost:5175?proxyPort=3002

If you encounter port conflicts:

bun run cleanup-ports

Debugging with the Inspector

The inspector UI allows you to:

• View all available MCP capabilities
• Execute tools and examine responses
• Analyze the JSON communication
• Test with different parameters

For more details, see the MCP Inspector GitHub repository.

Integration with Claude Desktop

Click to expand Claude Desktop integration

Test your MCP server directly with Claude:

1. Build:

bun run build  # You must build the project before running it

2. Configure Claude Desktop:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

3. Add the MCP configuration:

{
     "mcpServers": {
       "JIRA Tools": {
         "command": "node",
         "args": ["/absolute/path/to/your/project/dist/index.js"],
         "env": {
           "JIRA_USERNAME": "your-jira-username",
           "JIRA_API_TOKEN": "your-jira-api-token",
           "JIRA_HOST": "your-jira-host.atlassian.net"
         }
       }
     }
   }

4. Restart Claude Desktop and test with:

Show me my assigned JIRA issues.

🔌 Integration with Cursor IDE

> ⚠️ Important: You must build the project with `bun run build` before integrating with Cursor IDE or Claude Desktop.

Add this MCP server to your Cursor IDE's MCP configuration:

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"],
      "env": {
        "JIRA_USERNAME": "your-jira-username",
        "JIRA_API_TOKEN": "your-jira-api-token",
        "JIRA_HOST": "your-jira-host.atlassian.net"
      }
    }
  }
}

📁 Project Structure

src/
├── core/                    # Core functionality and configurations
│   ├── errors/             # Error handling utilities
│   ├── logging/            # Logging infrastructure
│   ├── responses/          # Response formatting
│   ├── server/             # MCP server implementation
│   ├── tools/              # Base tool interfaces
│   └── utils/              # Core utilities
├── features/               # Feature implementations
│   └── jira/              # JIRA API integration
│       ├── api/           # JIRA API client
│       ├── formatters/    # Response formatters
│       ├── tools/         # MCP tool implementations
│       └── utils/         # JIRA-specific utilities
└── test/                  # Test utilities and mocks
    ├── mocks/             # Mock factories
    └── utils/             # Test helpers

NPM Scripts

📝 Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development workflow
• Branching strategy
• Commit message format
• Pull request process
• Code style guidelines

📘 Resources

• Model Context Protocol Documentation
• MCP TypeScript SDK
• MCP Specification
• MCP Inspector
• JIRA REST API Documentation

📄 License

MIT © Stanislav Stepanenko