Skip to main content
Glama

JIRA MCP Server

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

{ "mcpServers": { "JIRA Tools": { "command": "bunx", "args": ["-y", "@dsazz/mcp-jira@latest"], "env": { "JIRA_HOST": "https://your-domain.atlassian.net", "JIRA_USERNAME": "your-email@example.com", "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=your-email@example.com 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

ToolDescriptionParametersReturns
jira_get_assigned_issuesRetrieves all issues assigned to youNoneMarkdown-formatted list of issues
jira_get_issueGets detailed information about a specific issueissueKey: Issue key (e.g., PD-312)Markdown-formatted issue details
jira_get_issue_commentsRetrieves comments for a specific issue with configurable optionsSee comment parameters belowMarkdown-formatted comments
jira_create_issueCreate new JIRA issues with comprehensive field supportSee issue creation parametersMarkdown-formatted creation result
jira_update_issueUpdate existing issues with field changes and status transitionsSee issue update parametersMarkdown-formatted update result
jira_get_projectsRetrieve and browse JIRA projects with filtering optionsSee project parametersMarkdown-formatted project list
jira_get_boardsGet JIRA boards (Scrum/Kanban) with advanced filteringSee board parametersMarkdown-formatted board list
jira_get_sprintsRetrieve sprint information for agile project managementSee sprint parametersMarkdown-formatted sprint list
jira_add_worklogAdd time tracking entries to issuesSee worklog parameters belowMarkdown-formatted worklog result
jira_get_worklogsRetrieve worklog entries for issues with date filteringSee worklog parameters belowMarkdown-formatted worklog list
jira_update_worklogUpdate existing worklog entriesSee worklog parameters belowMarkdown-formatted update result
jira_delete_worklogDelete worklog entries from issuesSee worklog parameters belowMarkdown-formatted deletion result
jira_get_current_userGet current authenticated user informationNoneMarkdown-formatted user details
search_jira_issuesSearch JIRA issues with JQL or helper parametersSee search parameters belowMarkdown-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

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

Test your MCP server directly with Claude:

  1. Build:
    bun run build # You must build the project before running it
  2. Configure Claude Desktop:
    nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
  3. 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" } } } }
  4. 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

CommandDescription
bun devRun the server in development mode with hot reload
bun buildBuild the project for production
bun startStart the production server
bun formatFormat code using Biome
bun lintLint code using Biome
bun checkRun Biome checks on code
bun typecheckRun TypeScript type checking
bun testRun tests
bun inspectStart the MCP Inspector for debugging
bun cleanup-portsClean 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

MIT © Stanislav Stepanenko


Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

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.

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.

  1. ✨ Features
    1. 🚀 Quick Start
      1. Installation
      2. Configuration
    2. 🛠️ Development Tools
      1. MCP Inspector
      2. Integration with Claude Desktop
    3. 🔌 Integration with Cursor IDE
      1. 🧰 Available Tools
        1. JIRA Tools
        2. System Time Tools
      2. 📁 Project Structure
        1. NPM Scripts
      3. 📘 Resources
        1. 📄 License

          Related MCP Servers

          • A
            security
            A
            license
            A
            quality
            Model 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,997
            MIT License
            • Apple
          • -
            security
            F
            license
            -
            quality
            A 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 -
            649
            1
          • A
            security
            F
            license
            A
            quality
            A Model Context Protocol server that enables integration with JIRA, allowing users to interact with JIRA tasks and issues through Claude AI assistant.
            Last updated -
            3
            2
            • Apple
          • -
            security
            F
            license
            -
            quality
            A 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 -
            • Linux
            • Apple

          View all related MCP servers

          MCP directory API

          We provide all the information about MCP servers via our MCP API.

          curl -X GET 'https://glama.ai/api/mcp/v1/servers/Dsazz/mcp-jira'

          If you have feedback or need assistance with the MCP directory API, please join our Discord server