Mcp Jira

Jira MCP Server

[](https://smithery.ai/server/jira-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, epiclink, priority, storypoints, 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: issuekey, summary, description, status, assignee, epiclink, priority, storypoints, labels, sprint, rankafterissue, rankbeforeissue, originalestimate, remainingestimate, customfields, 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: issuekey, workingdir, 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: issuekey, transitionid OR transitionname, comment (optional), resolution (optional), fields (optional), workingdir, 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

npm install -g jira-server

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

Installing via Smithery

To install Jira Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install jira-server --client claude

Manual Installation

1. Install dependencies:

# Clone and install dependencies
npm install

# Build the server
npm run build

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:

{
  "instances": {
    "primary": {
      "email": "your-email@company.com",
      "apiToken": "your-api-token-here",
      "domain": "your-domain",
      "projects": ["PROJ", "DEV", "OPS"]
    },
    "secondary": {
      "email": "your-email@otherdomain.com", 
      "apiToken": "your-other-api-token",
      "domain": "other-domain"
    }
  },
  "projects": {
    "PROJ": {
      "instance": "primary",
      "storyPointsField": "customfield_10016",
      "sprintField": "customfield_10020",
      "epicLinkField": "customfield_10014"
    },
    "DEV": {
      "instance": "primary",
      "storyPointsField": "customfield_10016"
    },
    "OTHER": {
      "instance": "secondary",
      "storyPointsField": "customfield_10020"
    }
  },
  "defaultInstance": "primary"
}

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:

{
  "projectKey": "YOUR_PROJECT_KEY",
  "storyPointsField": "customfield_XXXXX",  // Optional: auto-detected
  "sprintField": "customfield_YYYYY",       // Optional: auto-detected  
  "epicLinkField": "customfield_ZZZZZ"      // Optional: auto-detected
}

3. MCP Server Configuration

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

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server",
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token", 
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": true
    }
  }
}

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

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/path/to/jira-server/build/index.js"],
      "cwd": "/path/to/jira-server", 
      "env": {
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DOMAIN": "your-domain"
      },
      "disabled": false,
      "alwaysAllow": [
        "create_issue", "list_issues", "update_issue", "get_issue", "delete_issue", "add_comment",
        "list_instances", "create_component", "list_components", "get_component_progress",
        "create_version", "list_versions", "get_version_progress", 
        "search_issues_jql", "search_projects", "create_filter",
        "get_project_details", "get_project_statuses", "get_issue_types",
        "list_plans", "create_sprint", "update_sprint", "get_sprint_details",
        "create_epic", "update_epic_details", "bulk_update_issues"
      ]

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [cfdude](https://github.com/cfdude)
- **Source:** [cfdude/mcp-jira](https://github.com/cfdude/mcp-jira)
- **License:** MIT

Install and usage instructions live in the source repository linked above.