# Mcp Jira

> The best Jira MCP server you can ask for

- **Type:** MCP server
- **Install:** `agentstack add mcp-cfdude-mcp-jira`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [cfdude](https://agentstack.voostack.com/s/cfdude)
- **Installs:** 0
- **Category:** [Productivity](https://agentstack.voostack.com/c/productivity)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [cfdude](https://github.com/cfdude)
- **Source:** https://github.com/cfdude/mcp-jira

## Install

```sh
agentstack add mcp-cfdude-mcp-jira
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/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](https://id.atlassian.com/manage-profile/security/api-tokens)
3. **Project Access**: Read/write permissions for target projects

### Installation

#### Installing via npm

```bash
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](https://smithery.ai/server/jira-server):

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

#### Manual Installation
1. Install dependencies:

```bash
# 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:

```json
{
  "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:

```json
{
  "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`):

```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`):

```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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-cfdude-mcp-jira
- Seller: https://agentstack.voostack.com/s/cfdude
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.