🎯 JIRA MCP Server

✨ Features

• 🎯 Complete JIRA Integration Suite

  • Issue Management: Full CRUD operations for JIRA issues with comprehensive field support

  • Project & Board Discovery: Browse projects, boards, and sprints with advanced filtering

  • Smart Search: JQL and beginner-friendly search with rich formatting

  • Comment System: Access and manage issue comments with progressive disclosure

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

  • Modular Design: Feature-based architecture with clear separation of concerns

  • Robust HTTP Client: Refactored with dedicated utility classes for reliability

  • Comprehensive Testing: 822+ tests ensuring stability and reliability

  • Type Safety: Full TypeScript strict mode with enhanced error handling

• 🔍 Powerful Search & Discovery

  • Search issues using JQL (JIRA Query Language) or beginner-friendly parameters

  • Project, board, and sprint discovery with metadata and filtering

  • Rich markdown formatting with issue previews and direct navigation links

  • Advanced comment retrieval with author filtering and date ranges

• 📝 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

Related MCP server: MCP Server for Cursor

🆕 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:

Development Setup

For local development and testing:

Configuration

Create a .env file with the following variables:

🔑 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:

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:

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:

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:

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:

Worklog Parameters

The worklog tools support comprehensive time tracking:

jira_add_worklog:

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:

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:

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:

Required:

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

• worklogId: String - Worklog ID to delete

Examples:

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:

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

MCP Inspector

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

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:

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

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:

📁 Project Structure

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