Provides system time integration with customizable date and time formatting and locale support.
Allows access to Jira issues directly from the IDE, including viewing assigned issues, getting detailed information on specific issues, and converting Jira issues into local tasks.
🎯 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
🆕 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
Tool | Description | Parameters | Returns |
---|---|---|---|
jira_get_assigned_issues | Retrieves all issues assigned to you | None | Markdown-formatted list of issues |
jira_get_issue | Gets detailed information about a specific issue | issueKey : Issue key (e.g., PD-312) | Markdown-formatted issue details |
jira_get_issue_comments | Retrieves comments for a specific issue with configurable options | See comment parameters below | Markdown-formatted comments |
jira_create_issue | Create new JIRA issues with comprehensive field support | See issue creation parameters | Markdown-formatted creation result |
jira_update_issue | Update existing issues with field changes and status transitions | See issue update parameters | Markdown-formatted update result |
jira_get_projects | Retrieve and browse JIRA projects with filtering options | See project parameters | Markdown-formatted project list |
jira_get_boards | Get JIRA boards (Scrum/Kanban) with advanced filtering | See board parameters | Markdown-formatted board list |
jira_get_sprints | Retrieve sprint information for agile project management | See sprint parameters | Markdown-formatted sprint list |
jira_add_worklog | Add time tracking entries to issues | See worklog parameters below | Markdown-formatted worklog result |
jira_get_worklogs | Retrieve worklog entries for issues with date filtering | See worklog parameters below | Markdown-formatted worklog list |
jira_update_worklog | Update existing worklog entries | See worklog parameters below | Markdown-formatted update result |
jira_delete_worklog | Delete worklog entries from issues | See worklog parameters below | Markdown-formatted deletion result |
jira_get_current_user | Get current authenticated user information | None | Markdown-formatted user details |
search_jira_issues | Search JIRA issues with JQL or helper parameters | See search parameters below | Markdown-formatted search results |
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 emailreporter
: String - Reporter username or emaillabels
: Array - Labels to apply to the issuecomponents
: Array - Component namesfixVersions
: Array - Fix version namesaffectsVersions
: Array - Affected version namestimeEstimate
: String - Time estimate in JIRA format (e.g.,"2h"
,"1d 4h"
)dueDate
: String - Due date in ISO formatenvironment
: String - Environment descriptioncustomFields
: 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 titledescription
: String - Update descriptionpriority
: String - Change priorityassignee
: String - Reassign issuereporter
: String - Change reportertimeEstimate
: String - Update time estimatetimeSpent
: String - Log time spentdueDate
: String - Update due dateenvironment
: String - Update environment
Array Operations (add/remove/set):
labels
: Object - Modify labels ({operation: "add|remove|set", values: ["label1", "label2"]}
)components
: Object - Modify componentsfixVersions
: Object - Modify fix versionsaffectsVersions
: 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 resultsstartAt
: Number (default: 0) - Pagination offsetexpand
: 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 resultsstartAt
: Number (default: 0) - Pagination offsettype
: String - Board type ("scrum"
,"kanban"
)name
: String - Filter by board nameprojectKeyOrId
: 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 resultsstartAt
: Number (default: 0) - Pagination offsetstate
: String - Sprint state ("active"
,"closed"
,"future"
)
Examples:
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 donestarted
: 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 spentcomment
: String - Update commentstarted
: String - Update start time
jira_delete_worklog
Parameters:
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 retrieveorderBy
: String ("created"
or"updated"
, default:"created"
) - Sort order for comments
Advanced Options:
includeInternal
: Boolean (default: false) - Include internal/restricted commentsauthorFilter
: String - Filter comments by author name or emaildateRange
: Object - Filter by date range:from
: String (ISO date) - Start dateto
: 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 userproject
: String - Filter by project keystatus
: 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 resultsfields
: 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:
- Build:
- Configure Claude Desktop:
- Add the MCP configuration:
- Restart Claude Desktop and test with:
🔌 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
Command | Description |
---|---|
bun dev | Run the server in development mode with hot reload |
bun build | Build the project for production |
bun start | Start the production server |
bun format | Format code using Biome |
bun lint | Lint code using Biome |
bun check | Run Biome checks on code |
bun typecheck | Run TypeScript type checking |
bun test | Run tests |
bun inspect | Start the MCP Inspector for debugging |
bun cleanup-ports | Clean up ports used by the development server |
📝 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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Tools
A Model Context Protocol server that integrates JIRA directly into Cursor IDE, allowing users to view assigned issues, get detailed information on specific tickets, and convert JIRA issues into local tasks without leaving their editor.
Related MCP Servers
- AsecurityAlicenseAqualityModel Context Protocol (MCP) server for Atlassian Cloud products (Confluence and Jira). This integration is designed specifically for Atlassian Cloud instances and does not support Atlassian Server or Data Center deployments.Last updated -2,997MIT License
- -securityFlicense-qualityA Model Context Protocol server that integrates with Cursor IDE, providing real-time communication, modern web dashboards, and extensible tools via SSE and WebSocket connections.Last updated -6491
- AsecurityFlicenseAqualityA Model Context Protocol server that enables integration with JIRA, allowing users to interact with JIRA tasks and issues through Claude AI assistant.Last updated -32
- -securityFlicense-qualityA Model Context Protocol server that enables seamless integration between Cursor IDE and JIRA, allowing users to retrieve issues, execute JQL searches, and log work through natural language interactions.Last updated -