🎯 JIRA MCP Server

A powerful Model Context Protocol (MCP) server that brings Atlassian JIRA integration directly to any editor or application that supports MCP

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

{
  "mcpServers": {
    "JIRA Tools": {
      "command": "bunx",
      "args": ["-y", "@dsazz/mcp-jira@latest"],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_USERNAME": "[email protected]",
        "JIRA_API_TOKEN": "your-jira-api-token"
      }
    }
  }
}

Development Setup

For local development and testing:

# Clone the repository
git clone https://github.com/Dsazz/mcp-jira.git
cd mcp-jira

# Install dependencies
bun install

# Set up environment variables
cp .env.example .env
# Edit .env with your JIRA credentials

# Build the project
bun run build

# Test with MCP Inspector
bun run inspect

Configuration

Create a .env file with the following variables:

JIRA_HOST=https://your-instance.atlassian.net
JIRA_USERNAME[email protected]
JIRA_API_TOKEN=your-jira-api-token-here

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

# Basic issue creation
jira_create_issue projectKey:"PROJ" issueType:"Task" summary:"Fix login bug"

# Comprehensive issue with all fields
jira_create_issue projectKey:"PROJ" issueType:"Bug" summary:"Critical login issue" description:"Users cannot log in" priority:"High" assignee:"john.doe" labels:["urgent","security"] timeEstimate:"4h"

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:

# Update basic fields
jira_update_issue issueKey:"PROJ-123" summary:"Updated title" priority:"High"

# Add labels and transition status
jira_update_issue issueKey:"PROJ-123" labels:'{operation:"add",values:["urgent"]}' status:"In Progress"

# Log work and add comment
jira_update_issue issueKey:"PROJ-123" worklog:'{timeSpent:"2h",comment:"Completed testing"}'

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:

# Get all projects
jira_get_projects

# Get projects with additional details
jira_get_projects expand:["description","lead","issueTypes"] maxResults:20

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:

# Get all boards
jira_get_boards

# Get Scrum boards for specific project
jira_get_boards type:"scrum" projectKeyOrId:"PROJ"

# Search boards by name
jira_get_boards name:"Sprint Board" maxResults:10

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:

# Get all sprints for a board
jira_get_sprints boardId:123

# Get only active sprints
jira_get_sprints boardId:123 state:"active"

# Get sprints with pagination
jira_get_sprints boardId:123 maxResults:10 startAt:20

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 done
started: 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 spent
comment: String - Update comment
started: String - Update start time

jira_delete_worklog Parameters:

Required:

issueKey: String - Issue key (e.g., "PROJ-123")
worklogId: String - Worklog ID to delete

Examples:

# Add worklog entry
jira_add_worklog issueKey:"PROJ-123" timeSpent:"2h" comment:"Fixed authentication bug"

# Get all worklogs for an issue
jira_get_worklogs issueKey:"PROJ-123"

# Get worklogs from last week
jira_get_worklogs issueKey:"PROJ-123" startedAfter:"2025-05-29T00:00:00.000Z"

# Update worklog
jira_update_worklog issueKey:"PROJ-123" worklogId:"12345" timeSpent:"3h" comment:"Updated work description"

# Delete worklog
jira_delete_worklog issueKey:"PROJ-123" worklogId:"12345"

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:

# Basic usage - get 10 most recent comments
jira_get_issue_comments PROJ-123

# Get more comments with specific ordering
jira_get_issue_comments PROJ-123 maxComments:25 orderBy:"updated"

# Advanced filtering
jira_get_issue_comments PROJ-123 authorFilter:"john.doe" includeInternal:true

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

# Format code
bun run format

# Check code for issues
bun run check

# Type check
bun run typecheck

# Run tests
bun test

MCP Inspector

Click to expand MCP Inspector details

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

# Run the inspector (no separate build step needed)
bun run inspect

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:

bun run cleanup-ports

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

Click to expand Claude Desktop integration

Test your MCP server directly with Claude:

Build:

bun run build  # You must build the project before running it

Configure Claude Desktop:

nano ~/Library/Application\ Support/Claude/claude_desktop_config.json

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"
      }
    }
  }
}

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:

{
  "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"
      }
    }
  }
}

📁 Project Structure

src/
├── core/                    # Core functionality and configurations
│   ├── errors/             # Error handling utilities
│   ├── logging/            # Logging infrastructure
│   ├── responses/          # Response formatting
│   ├── server/             # MCP server implementation
│   ├── tools/              # Base tool interfaces
│   └── utils/              # Core utilities
├── features/               # Feature implementations
│   └── jira/              # JIRA API integration
│       ├── api/           # JIRA API client
│       ├── formatters/    # Response formatters
│       ├── tools/         # MCP tool implementations
│       └── utils/         # JIRA-specific utilities
└── test/                  # Test utilities and mocks
    ├── mocks/             # Mock factories
    └── utils/             # Test helpers

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

📄 License

_{Built with ❤️ for a better developer experience}

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
src		src
.cursorignore		.cursorignore
.cursorindexingignore		.cursorindexingignore
.env.example		.env.example
.env.test		.env.test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
bunfig.toml		bunfig.toml
glama.json		glama.json
package.json		package.json
tsconfig.json		tsconfig.json

License

Dsazz/mcp-jira

Folders and files

Latest commit

History

Repository files navigation

🎯 JIRA MCP Server

✨ Features

🆕 What's New in v0.5.0

🏗️ Major Architecture Overhaul

🧪 Enhanced Testing & Quality

🔧 Technical Improvements

🚀 Performance & Reliability

🚀 Quick Start

Installation

Development Setup

Configuration

🧰 Available Tools

Core JIRA Tools

Issue Creation Parameters

Issue Update Parameters

Project Parameters

Board Parameters

Sprint Parameters

Worklog Parameters

Comment Parameters

Search Parameters

🛠️ Development Tools

Code Quality Tools

MCP Inspector

Debugging with the Inspector

Integration with Claude Desktop

🔌 Integration with Cursor IDE

📁 Project Structure

NPM Scripts

📝 Contributing

📘 Resources

📄 License

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Languages

Packages