@imazhar101/mcp-jira-server

Jira MCP Server

A comprehensive Jira integration for the Model Context Protocol (MCP) that enables issue management, project tracking, and workflow automation.

Overview

The Jira MCP Server provides seamless integration with Atlassian Jira, allowing you to perform all essential issue management operations through the MCP protocol. This server is part of the MCP Suite monorepo and leverages shared utilities for consistent development patterns.

Features

• Issue Management: Create, read, update, and delete Jira issues
• Project Operations: List and retrieve project information
• Workflow Management: Transition issues through workflow states
• Search & Query: Advanced issue searching using JQL (Jira Query Language)
• Comments: Add and manage issue comments
• Assignment: Assign issues to team members

Setup

Prerequisites

• Node.js 18+
• Access to a Jira instance (Cloud or Server)
• Jira API token for authentication

Environment Variables

Create a .env file in the project root with the following variables:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=[e-mail]
JIRA_API_TOKEN=your-api-token

Getting Your Jira API Token

• Go to Atlassian Account Settings
• Click "Create API token"
• Enter a label for your token
• Copy the generated token to your .env file

Installation & Usage

Option 1: npm Package (Recommended)

# Install globally
npm install -g @imazhar101/mcp-jira-server

# Or run directly with npx
npx @imazhar101/mcp-jira-server

Option 2: Build from Source

As Part of MCP Suite

From the project root:

# Install dependencies
npm install

# Build the server
npm run build

# Start the Jira server
npm run build:server jira

Standalone Usage

# Navigate to the jira server directory
cd servers/jira

# Install dependencies
npm install

# Build the server
npm run build

# Start the server
npm start

Cline MCP Configuration

To use this server with Cline (VS Code extension), add the following to your Cline MCP settings:

File Location:

• macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
• Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Configuration:

{
  "mcpServers": {
    "jira-integration": {
      "command": "npx",
      "args": ["@imazhar101/mcp-jira-server"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "[e-mail]",
        "JIRA_API_TOKEN": "your-api-token"
      },
      "disabled": false,
      "alwaysAllow": ["search_issues", "get_issue", "list_projects"]
    }
  }
}

Available Tools

Issue Operations

search_issues

Search for issues using JQL (Jira Query Language).

Parameters:

• jql (string): The JQL query string
• maxResults (number, optional): Maximum number of results (default: 50)
• startAt (number, optional): Starting index for pagination (default: 0)

Example:

{
  "jql": "project = PROJ AND status = 'To Do'",
  "maxResults": 25
}

get_issue

Retrieve detailed information about a specific issue.

Parameters:

• issueIdOrKey (string): The issue ID or key (e.g., "PROJ-123")

create_issue

Create a new Jira issue.

Parameters:

• project (string): Project key
• summary (string): Issue summary/title
• description (string, optional): Issue description
• issueType (string): Issue type (e.g., "Task", "Bug", "Story")
• priority (string, optional): Priority level
• assignee (string, optional): Assignee account ID
• labels (array, optional): Array of label strings

update_issue

Update an existing issue.

Parameters:

• issueIdOrKey (string): The issue ID or key
• summary (string, optional): New summary
• description (string, optional): New description
• priority (string, optional): New priority
• assignee (string, optional): New assignee account ID
• labels (array, optional): New labels array

transition_issue

Change the status of an issue through workflow transitions.

Parameters:

• issueIdOrKey (string): The issue ID or key
• transitionId (string): The transition ID to execute

get_issue_transitions

Get available transitions for an issue.

Parameters:

• issueIdOrKey (string): The issue ID or key

assign_issue

Assign an issue to a user.

Parameters:

• issueIdOrKey (string): The issue ID or key
• assignee (string): Account ID of the assignee

delete_issue

Delete an issue.

Parameters:

• issueIdOrKey (string): The issue ID or key

Comment Operations

add_comment

Add a comment to an issue.

Parameters:

• issueIdOrKey (string): The issue ID or key
• body (string): Comment text

Project Operations

list_projects

List all accessible projects.

Parameters: None

get_project

Get detailed information about a specific project.

Parameters:

• projectIdOrKey (string): The project ID or key

Error Handling

The server includes comprehensive error handling:

• Authentication Errors: Invalid credentials or expired tokens
• Permission Errors: Insufficient permissions for operations
• Validation Errors: Invalid parameters or data formats
• API Errors: Jira API-specific errors with detailed messages

All errors are logged with contextual information and returned with appropriate error codes.

Development

Project Structure

servers/jira/
├── src/
│   ├── handlers/
│   │   └── jira-service.ts    # Jira API service implementation
│   ├── tools/
│   │   └── index.ts           # MCP tool definitions
│   ├── types/                 # TypeScript type definitions
│   ├── types.ts              # Main type definitions
│   └── index.ts              # Server entry point
├── package.json
├── tsconfig.json
└── README.md

Building

# Build TypeScript
npm run build

# Watch mode for development
npm run dev

Testing

Tests are located in the main tests/ directory:

# Run integration tests
cd ../.. && npm test

# Run specific Jira tests
npx vitest run tests/integration/jira-server.test.ts

Contributing

• Follow the established patterns in the MCP Suite
• Use the shared utilities from ../../shared/
• Add comprehensive error handling
• Update tests for new functionality
• Follow TypeScript best practices

Support

• Check the main MCP Suite README for general information
• Review the shared utilities documentation for development guidance
• Create issues in the main repository for bugs or feature requests

License

This project is licensed under the MIT License - see the LICENSE file for details.