Jira MCP Server

A comprehensive Model Context Protocol server that provides enterprise-level integration with Jira's REST API, enabling AI assistants to perform advanced project management, analytics, and strategic planning tasks.

Note: This is a maintained fork of 1broseidon/mcp-jira-server. We are grateful for the original work and continue to develop and enhance this project independently. All credit for the initial implementation goes to the original authors.

🚀 Features Overview

This server transforms basic Jira functionality into a complete project management platform with enterprise-level concurrency and thread safety:

🔒 Enterprise Concurrency & Thread Safety

• Thread-Safe Multi-Client Support: Multiple Claude Code sessions can safely use the same server simultaneously

• Session-Based State Isolation: Each client connection gets its own isolated session state

• Per-Session Configuration Caching: Prevents race conditions and improves performance

• Automatic Session Management: 30-minute session timeout with graceful cleanup

• Production-Ready Architecture: Designed for high-concurrency enterprise environments

Core Issue Management

• Create, update, delete, and manage Jira issues

• Advanced issue querying with JQL support

• Story points and sprint management

• Epic linking and hierarchy management

• Comment and attachment handling

• 🆕 Time Tracking Support: Native time tracking with original_estimate and remaining_estimate fields

• 🆕 Workflow Transitions: Complete workflow management with transition tools

• Multi-instance support: Work with multiple Jira Cloud environments from one session

🏗️ Project Structure & Organization

• Component Management: Organize work by feature areas and teams

• Version/Release Tracking: Manage release milestones and progress

• Project Discovery: Search and analyze projects across your Jira instance

• Configuration Analysis: Understand project setup and optimize workflows

📊 Advanced Analytics & Insights

• Progress Tracking: Component and version progress with visual indicators

• Workflow Analysis: Understand status transitions and bottlenecks

• Team Performance: Assignee workload distribution and activity tracking

• Strategic Planning: High-level roadmap and plan management

🔍 Advanced Querying & Automation

• JQL Search: Execute complex queries with comprehensive analytics

• Saved Filters: Create reusable queries with sharing permissions

• Cross-Project Search: Discover and analyze projects organization-wide

• Bulk Operations: Efficiently manage multiple issues and projects

📋 Complete Tool Reference

Issue Management Tools

create_issue

Creates new Jira issues with comprehensive field support

• Parameters: summary, description, type, epic_link, priority, story_points, labels, sprint, projectKey

• Features: Auto-detects story points fields, supports sprint assignment

list_issues

Lists project issues with filtering and sorting options

• Parameters: status, epic_key, sortField, sortOrder, projectKey

• Features: Visual separators, sprint information display, rank-based sorting

update_issue

Updates existing issues with full field support including time tracking

• Parameters: issue_key, summary, description, status, assignee, epic_link, priority, story_points, labels, sprint, rank_after_issue, rank_before_issue, original_estimate, remaining_estimate, custom_fields, projectKey

• Features: Issue ranking, sprint management, epic linking, intelligent assignee resolution, time tracking support, dynamic component field handling

get_issue

Retrieves detailed issue information

• Parameters: issue_key

• Features: Complete issue metadata, comments, relationships

delete_issue

Safely removes issues from projects

• Parameters: issue_key

add_comment

Adds comments to existing issues

• Parameters: issue_key, comment

get_transitions 🆕 v1.1.0

Get available workflow transitions for an issue

• Parameters: issue_key, working_dir, instance (optional)

• Features: Lists available transitions, required fields, and transition IDs

• Use Case: Understand workflow options before performing transitions

transition_issue 🆕 v1.1.0

Perform workflow transitions on issues (e.g., move to "In Progress", "Done")

• Parameters: issue_key, transition_id OR transition_name, comment (optional), resolution (optional), fields (optional), working_dir, instance (optional)

• Features: Transition by name or ID, automatic resolution setting, comment addition

• Use Case: Automate status changes and workflow progression

list_custom_fields 🆕 v1.1.0

Discover available custom fields for configuration

• Parameters: working_dir, instance (optional), projectKey (optional), showSystemFields (optional)

• Features: Field discovery, configuration examples, type classification

• Use Case: New user onboarding, field configuration, system exploration

⚙️ Configuration & Instance Management

list_instances

Lists available Jira instances and their configurations

• Features: Instance discovery, project mappings, configuration guidance, setup validation

• Use Cases: Multi-instance setup verification, troubleshooting, configuration planning

🏗️ Project Structure Tools

create_component

Creates feature-based project components

• Parameters: name, description, leadAccountId, assigneeType

• Features: Lead assignment, automatic issue routing

list_components

Lists all project components with details

• Features: Component categorization, lead information, usage statistics

get_component_progress

Comprehensive component analytics and progress tracking

• Features: Progress percentages, status breakdowns, recent activity analysis, workload distribution

create_version

Creates project versions for release management

• Parameters: name, description, startDate, releaseDate, released, archived

• Features: Release timeline management, milestone tracking

list_versions

Lists project versions with categorization

• Features: Active/released/archived separation, timeline information, overdue warnings

get_version_progress

Detailed version progress and timeline analysis

• Features: Completion tracking, issue breakdowns, deadline monitoring, timeline insights

🔍 Advanced Query Tools

search_issues_jql

Execute advanced JQL queries with comprehensive analytics

• Parameters: jql, maxResults, startAt, fields, expand, validateQuery

• Features: Query validation, result analytics, pagination, performance optimization

search_projects

Discover and search projects organization-wide

• Parameters: query, typeKey, categoryId, status, maxResults, startAt, expand

• Features: Cross-project discovery, metadata analysis, categorization

create_filter

Create saved filters for consistent tracking

• Parameters: name, jql, description, favourite, sharePermissions

• Features: Permission management, team collaboration, query reuse

📊 Project Analysis Tools

get_project_details

Comprehensive project information and structure analysis

• Parameters: projectKey, expand

• Features: Complete metadata, component/version summaries, permission analysis

get_project_statuses

Workflow and status configuration analysis

• Features: Status categorization, workflow optimization insights, transition mapping

get_issue_types

Issue type discovery and configuration analysis

• Features: Type hierarchy, field requirements, usage guidelines

detect_project_fields

🆕 Field Configuration Discovery - Essential for new user onboarding

• Parameters: working_dir, projectKey, instance (optional)

• Purpose: Automatically detect custom field IDs required for project configuration

• Output: Ready-to-copy configuration snippets for .jira-config.json

• Detects: Story Points, Sprint, and Epic Link field IDs using intelligent heuristics

• Multi-Instance: Full support for multiple Jira environments

• Session-Aware: Provides guidance only on first project access per session

• Use Case: Eliminates manual field ID hunting in Jira admin interface

🌉 Cross-Server Integration Tools

jira_health_check

🆕 Server Health Monitoring - Monitor Jira server status and cross-server integration

• Purpose: Check server health, uptime, and cross-server connectivity

• Output: Comprehensive health status, configuration details, supported operations

• Cross-Server: Shows integration status with Confluence MCP servers

• Session Info: Real-time session count and activity monitoring

confluence_health_check

🆕 Cross-Server Health Check - Monitor Confluence server connectivity from Jira

• Purpose: Verify Jira-to-Confluence integration status and capabilities

• Output: Connection status, endpoint verification, integration configuration

🎯 Strategic Planning Tools

list_plans

Strategic plan management (Jira Premium feature)

• Features: High-level roadmap tracking, timeline analysis, team metrics

Sprint & Epic Management Tools

create_sprint

Creates new sprints with goals and timelines

• Parameters: name, goal, startDate, endDate, boardId, projectKey

update_sprint

Modifies existing sprint details and timeline

• Parameters: sprintId, name, goal, startDate, endDate, state

get_sprint_details

Comprehensive sprint progress and analytics

• Features: Issue tracking, velocity insights, burndown data

move_issues_to_sprint

Bulk sprint assignment for issues

• Parameters: sprintId, issueKeys

complete_sprint

Closes active sprints and handles remaining work

• Parameters: sprintId

create_epic

Creates new epics for large feature organization

• Parameters: name, summary, description, priority, labels, projectKey

create_epic_with_issues

Creates an epic with linked issues in a single operation ⚡

• Parameters: epic (name, summary, description, priority, labels), issues (array of issue data)

• Features: Reduces API calls, ensures proper linking, comprehensive error handling

• Benefits: Atomic operation, validates all issue types, automatic assignee resolution

update_epic_details

Updates epic properties and status

• Parameters: epicKey, name, summary, color, done

rank_epics & rank_issues

Manages epic and issue prioritization

• Features: Relative ranking, priority management

bulk_update_issues

Efficiently updates multiple issues simultaneously

• Parameters: issueKeys, updates (status, assignee, labels, priority, sprint, storyPoints)

• Features: Bulk operations, error handling per issue, intelligent assignee resolution

Board & Reporting Tools

list_boards

Lists available Kanban and Scrum boards

• Features: Board categorization, project association

get_board_configuration

Analyzes board setup and column configuration

• Features: Workflow mapping, column analysis

get_sprint_report, get_velocity_chart_data, get_burndown_chart_data

Advanced sprint and team performance analytics

• Features: Velocity tracking, burndown analysis, performance insights

🛠️ Setup & Configuration

Prerequisites

1. Jira Account: With API access and appropriate permissions

2. API Token: Generated from Atlassian Account Settings

3. Project Access: Read/write permissions for target projects

Installation

Installing via npm

After installation, the jira-server command will be available globally.

Installing via Smithery

To install Jira Server for Claude Desktop automatically via Smithery:

Manual Installation

1. Install dependencies:

Configuration

1. Multi-Instance Configuration (Recommended)

The Jira MCP Server supports multiple Jira instances from a single Claude Desktop session. This enables seamless switching between different Jira Cloud environments based on project keys.

Create .jira-config.json in your working directory:

Instance Selection Logic

The server automatically selects the correct Jira instance using this priority order:

1. Explicit Override: Manual instance parameter in tool calls

2. Project Mapping: Direct project-to-instance configuration in projects section

3. Instance Project Lists: Projects listed in instance projects arrays

4. Default Instance: Fallback to defaultInstance setting

5. Single Instance: Use the only available instance if just one is configured

2. Legacy Single-Instance Configuration (Still Supported)

For single Jira instance setups, use the simplified format:

3. MCP Server Configuration

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

For VS Code Cline Extension (~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/cline_mcp_settings.json):

For OpenCode (opencode.json in project or ~/.config/opencode/opencode.json):

JIRA_CONFIG_PATH can be absolute, relative to the config file, or use ~ for the home directory. If you register the server under a different MCP name, set JIRA_MCP_KEY to that value so the loader can locate the correct block.

4. Cross-Server Integration Configuration

For cross-server integration between Jira and Confluence MCP servers, you'll need to install and configure the companion confluence-cloud-mcp server alongside this Jira server.

Add Confluence API configuration to your .jira-config.json:

This enables tools like jira_health_check, confluence_health_check, and cross-server document creation capabilities.

Cross-Server Integration Benefits:

• Bidirectional Linking: Create smart links between Jira issues and Confluence pages

• Automated Documentation: Generate Confluence pages directly from Jira issues (epics, features, etc.)

• Health Monitoring: Monitor both servers and their integration status

• Unified Workflow: Seamlessly switch between issue tracking and documentation within the same AI session

For complete setup instructions and advanced cross-server features, see the confluence-cloud-mcp documentation.

🎯 Usage Examples

Multi-Instance Management

Instance Discovery

Automatic Instance Selection

Manual Instance Override

Project Planning Workflow

Progress Tracking & Analytics

Advanced Query & Automation

🆕 Time Tracking & Workflow Management (v1.1.0)

Time Tracking Examples

Workflow Transition Examples

Field Discovery Examples

Epic with Issues - Bulk Creation ⚡

The new create_epic_with_issues tool allows you to create an epic and multiple linked issues in a single operation:

Benefits of Bulk Creation:

• Reduced API Calls: Single operation instead of multiple separate calls

• Automatic Linking: All issues are automatically linked to the epic

• Atomic Operation: Either all items are created successfully or none are

• Comprehensive Validation: Validates epic and all issues before creation

• Enhanced Error Handling: Detailed feedback on any validation failures

• Intelligent Assignee Resolution: Automatically resolves user names/emails to account IDs

Assignee Management Examples

The MCP Jira Server provides intelligent assignee resolution that accepts display names, emails, or account IDs and automatically resolves them to the correct Jira account.

Individual Issue Assignment

Bulk Assignment Operations

Assignee Resolution Logic

The system automatically handles user resolution using this priority order:

1. Exact Display Name Match: "Esther Yang" → Exact match in Jira users

2. Email Address Match: "esther.yang@company.com" → Match by email

3. Partial Name Match: "Esther" → Single partial match found

4. Account ID Pass-through: If already an account ID, uses as-is

Error Handling:

• No Match Found: Clear error message with suggested similar names

• Multiple Matches: Lists all possibilities and asks for more specificity

• Invalid Users: Validates user exists and is active

Special Values:

• "unassigned", null, or "" → Unassigns the issue

• Account IDs starting with specific patterns are used directly

🔧 Advanced Features

Intelligent Field Detection

• Automatically detects custom fields (Story Points, Sprint, Epic Link)

• Provides configuration guidance in debug logs

• Supports manual field ID override

Cross-Project Operations

• Search and manage issues across multiple projects

• Project discovery and analysis capabilities

• Organization-wide reporting and insights

Performance Optimization

• Efficient batch operations for bulk updates

• Pagination support for large datasets

• Query validation and optimization suggestions

Rich Analytics & Reporting

• Visual progress indicators and percentages

• Timeline analysis with deadline tracking

• Team performance and workload distribution

• Historical trend analysis and insights

🐛 Troubleshooting

Debug Logging

Monitor server activity with detailed logs:

Common Issues

Field Detection Problems

• New Users: Use detect_project_fields tool to automatically discover field IDs

• Missing Fields: Tools now provide automatic guidance on first project access per session

• Check debug logs for "Found [Field] field" messages

• Verify custom field IDs in project admin

• Ensure proper field permissions

Query Performance

• Use validateQuery: true for JQL testing

• Implement pagination for large result sets

• Monitor query complexity in debug logs

Configuration Issues

• Server checks multiple config locations in order:

  1. Working directory parameter (working_dir)

  2. Current working directory (process.cwd())

  3. Server installation directory

• Verify .jira-config.json format and permissions

Multi-Instance Configuration Issues

• Instance Not Found: Use list_instances to verify instance names and configurations

• Wrong Instance Selected: Check project mappings in projects section and instance projects arrays

• Authentication Failures: Verify each instance has correct email, apiToken, and domain

• Project Key Conflicts: Ensure project keys are unique across instances or properly mapped

• Configuration Validation: Use list_instances for setup verification and troubleshooting guidance

API Rate Limiting

• Implement delays between bulk operations

• Use batch operations where available

• Monitor API response headers for rate limit status

Enhanced Error Messages 🎯

The server now provides detailed, user-friendly error messages with specific troubleshooting guidance:

Field Validation Errors

• Detailed Field Issues: Clear explanations for each field problem

• User-Friendly Names: Technical field IDs converted to readable names (e.g., customfield_10011 → Epic Name)

• Field-Specific Guidance: Targeted advice for common field issues

Context-Aware Troubleshooting

• Permission Issues: Specific steps for resolving access problems

• Configuration Problems: Guidance for field and project setup issues

• Validation Failures: Clear explanation of what went wrong and how to fix it

Example Enhanced Error

Error Codes & Resolution

🚀 Development

Development Setup

Testing

The project includes comprehensive Jest testing with ESM and TypeScript support:

Test Structure:

• tests/unit/ - Unit tests for individual modules (config, formatting, ADF conversion)

• tests/integration/ - Integration tests for server functionality

• Uses Jest with ts-jest for TypeScript ESM support

• Tests are automatically run in CI/CD pipeline

Key Features:

• ESM module testing with .js extension imports

• TypeScript compilation via ts-jest

• Node.js experimental VM modules for ESM compatibility

• Comprehensive coverage for utilities and core functionality

Contributing

1. Field Detection: Add new custom field support in src/config/config.ts

2. Tool Development: Follow existing patterns in src/tools/

3. API Extensions: Extend base client in src/jira-client.ts

4. Testing: Add comprehensive tests for new functionality

📈 Enterprise Features

Strategic Planning Integration

• Links tactical work to strategic initiatives

• Portfolio-level reporting and insights

• Cross-project dependency tracking

Advanced Analytics

• Custom metrics and KPI tracking

• Team performance benchmarking

• Predictive delivery forecasting

Workflow Optimization

• Bottleneck identification and resolution

• Process improvement recommendations

• Automation opportunity discovery

Security & Compliance

• Audit trail and change tracking

• Permission analysis and optimization

• Data governance and compliance reporting

Transform your Jira experience from basic issue tracking to comprehensive project management and strategic planning platform.