jira-backlog-manager-mcp

pointdotcom-eng/jira-backlog-manager-mcp

3.2

If you are the rightful owner of jira-backlog-manager-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The JIRA Backlog Manager MCP Server is a specialized Model Context Protocol server designed to enhance JIRA backlog management through intelligent analysis and management tools.

Tools
3
Resources
0
Prompts
0

JIRA Backlog Manager MCP Server

A Model Context Protocol (MCP) server that provides intelligent tools for analyzing and managing JIRA backlogs. This server offers capabilities for backlog analysis, ticket splitting suggestions, and smart search functionality.

Why a Custom JIRA MCP?

While other JIRA MCP implementations exist, this custom server provides:

  • Enhanced Security: Built specifically for Point's infrastructure with controlled data access
  • Tailored Functionality: Features designed for Point's specific backlog management workflows
  • Complete Customization: Easy to extend and modify for evolving team needs
  • Direct Integration: Connects directly to your JIRA instance without additional intermediary services

Features

  • 📊 Backlog Data Analysis: Fetch structured backlog data with flexible filtering
  • 🔍 Smart Search: Natural language and JQL-powered issue search
  • ✂️ Ticket Splitting: AI-powered suggestions for breaking down large tickets
  • 👥 Team Workload Analysis: Real-time capacity and assignment analysis
  • 🎯 Team Expertise Mapping: Skills tracking via technology signals (components ignored)
  • 🔗 Dependency Analysis: Blocking relationships and bottleneck identification
  • 📈 Historical Metrics: Project-level performance trends (velocity and quality)
  • 🏷️ Flexible Filtering: Filter by status, issue types, and other criteria

AI-Powered Backlog Management Examples

Check for Duplicate Issues
Check for duplicates in our backlog - look for similar summaries and descriptions
Suggest Issue Assignments
Which unassigned tickets should be assigned to specific team members?
Identify Issues with Unresolved Questions
Which tickets have unresolved questions or are blocked?
Backlog Health Analysis
Analyze our backlog health and suggest improvements
Sprint Planning Assistance
Help me plan the next sprint based on priorities and team capacity

Tools Available

Core Tools

get_backlog_data

Fetch comprehensive backlog data for analysis including issue details, status, assignees, and metadata.

Parameters:

  • project (string, optional): Project key (default: "GRO")
  • maxResults (number, optional): Max issues to fetch (10-500, default: 200)
  • statusFilter (string, optional): Comma-separated statuses (e.g., "BACKLOG,IN PROGRESS")
  • issueTypes (string, optional): Comma-separated types (e.g., "Story,Bug,Epic")
smart_search_issues

Search issues using natural language queries or JQL with AI assistance.

Parameters:

  • query (string, required): Natural language query or JQL
  • project (string, optional): Project key (default: "GRO")
  • maxResults (number, optional): Max results (1-100, default: 50)
get_ticket_info_for_splitting

Get comprehensive ticket information including comments and links for splitting analysis.

Parameters:

  • issueKey (string, required): The issue key to get information for
perform_split

Split a ticket into multiple new tickets with optional updates to the original ticket.

Parameters:

  • originalTicket (string, required): The original ticket key to split
  • newTickets (array, required): Array of new tickets to create, each with summary, description, and optional fields like issueType, assignee, priority, labels, components, and storyPoints
  • updateOriginal (object, optional): Updates to apply to the original ticket (e.g., new summary, description, or status)
  • linkType (string, optional): Type of link to create between original and new tickets (default: relates)
  • dryRun (boolean, optional): If true, only shows what would be created without making changes (default: true)

Notes:

  • Descriptions are automatically converted to Atlassian Document Format (ADF) for Jira Cloud v3.
  • Assignee displayName is resolved to an accountId for Jira Cloud v3.
  • If the original issue has a parent (e.g., Epic or parent Story), the new tickets inherit that parent automatically.
  • Error messages now include raw Jira error payload details to aid troubleshooting.
merge_tickets

Merge multiple related tickets into a single primary ticket. Performs analysis in dry-run, then updates the primary ticket and closes secondaries using a duplicate-first strategy.

Parameters:

  • ticketKeys (array, required): Array of ticket keys to merge (minimum 2)
  • targetTicket (string, optional): Primary ticket to merge others into. If omitted, selects primary via mergeStrategy.
  • dryRun (boolean, optional): If true, only analyzes without changes (default: true)
  • mergeStrategy (string, optional): Primary selection strategy: "smart" | "oldest" | "newest" | "highest_priority" | "most_detailed" (default: "smart")

Notes:

  • Descriptions and comments are sent using Jira Cloud ADF.
  • Secondary tickets are closed with a Duplicate resolution when supported; otherwise, transitioned to a Done-category status.
  • Transition availability and required fields depend on your Jira workflow; the server will fall back when duplicate-specific transitions aren't available.
  • Errors include raw Jira response payload details to aid troubleshooting.

Advanced Analytics Tools

get_team_workload

Get current team workload and capacity analysis. Shows active assignments, story points in progress, and available capacity.

Parameters:

  • project (string, optional): Project key (default: "GRO")
  • sprintFilter (string, optional): Filter by sprint status: "active", "future", or "all" (default: active)

Example Usage:

// Get current team workload
use_mcp_tool("jira-backlog-manager", "get_team_workload", {})

// Focus on future sprint capacity
use_mcp_tool("jira-backlog-manager", "get_team_workload", {
  "sprintFilter": "future"
})
get_team_expertise

Analyze team member expertise based on historical assignments and technology signals (components ignored).

Parameters:

  • project (string, optional): Project key (default: "GRO")
  • lookbackDays (number, optional): Days to look back for historical data (30-365, default: 90)

Example Usage:

// Get team expertise analysis
use_mcp_tool("jira-backlog-manager", "get_team_expertise", {
  "lookbackDays": 180
})
get_ticket_dependencies

Analyze ticket dependencies, blocking relationships, and related work.

Parameters:

  • issueKey (string, optional): Issue key to analyze (if not provided, analyzes all active tickets)
  • project (string, optional): Project key (default: "GRO")

Example Usage:

// Analyze all dependencies project-wide
use_mcp_tool("jira-backlog-manager", "get_ticket_dependencies", {})

// Analyze dependencies for specific ticket
use_mcp_tool("jira-backlog-manager", "get_ticket_dependencies", {
  "issueKey": "GRO-123"
})
get_historical_metrics

Get project-level historical metrics (overall and by issue type) with trends. No team stats or hard-coded recommendations.

Parameters:

  • project (string, optional): Project key (default: "GRO")
  • issueType (string, optional): Filter by issue type (Bug, Story, Epic, etc.)
  • component (string, optional): Filter by component name
  • lookbackDays (number, optional): Days to look back (30-730, default: 180)

Notes:

  • qualityTrend.bugRate is computed as (bugs created) / (all issues created) per period within the current filter scope. The response also includes bugCount and totalCreated for each period to provide context.

Example Usage:

// Get overall performance metrics
use_mcp_tool("jira-backlog-manager", "get_historical_metrics", {})

// Analyze bug resolution performance
use_mcp_tool("jira-backlog-manager", "get_historical_metrics", {
  "issueType": "Bug",
  "lookbackDays": 90
})

Installation & Setup

Prerequisites

  • Node.js 18+
  • TypeScript
  • JIRA Cloud instance with API access
  • JIRA API token

Environment Variables

Create a .env file or set the following environment variables:

JIRA_BASE_URL=https://your-domain.atlassian.net
JIRA_EMAIL=your-email@company.com
JIRA_API_TOKEN=your-api-token
JIRA_PROJECT_KEY=YOUR_PROJECT_KEY  # Optional, defaults to "GRO"

Getting Your JIRA API Token

  1. Go to Atlassian Account Settings
  2. Click "Create API token"
  3. Give it a descriptive name (e.g., "MCP Backlog Manager")
  4. Copy the generated token - save it securely as it won't be shown again

Build & Run

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

Development

# Watch mode for development
npm run dev

MCP Configuration

Add this server to your MCP client configuration:

{
  "mcpServers": {
    "jira-backlog-manager": {
      "command": "node",
      "args": ["/path/to/jira-backlog-manager/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_PROJECT_KEY": "YOUR_PROJECT_KEY"
      }
    }
  }
}

Usage Examples

Basic Tool Usage

Get Backlog Data
// Get all backlog issues
use_mcp_tool("jira-backlog-manager", "get_backlog_data", {})

// Filter by status and issue type
use_mcp_tool("jira-backlog-manager", "get_backlog_data", {
  "statusFilter": "BACKLOG,TO DO",
  "issueTypes": "Story,Bug",
  "maxResults": 100
})
Smart Search
// Natural language search
use_mcp_tool("jira-backlog-manager", "smart_search_issues", {
  "query": "authentication issues with login"
})

// JQL search
use_mcp_tool("jira-backlog-manager", "smart_search_issues", {
  "query": "assignee = currentUser() AND status = 'In Progress'"
})
Split Large Tickets

Example flow:

  1. Get context for splitting (comments, links, parent, etc.)
use_mcp_tool("jira-backlog-manager", "get_ticket_info_for_splitting", {
  "issueKey": "GRO-591"
})
  1. Dry-run the split (no changes made)
use_mcp_tool("jira-backlog-manager", "perform_split", {
  "originalTicket": "GRO-591",
  "newTickets": [
    { "summary": "Subtask 1", "description": "Details for subtask 1" },
    { "summary": "Subtask 2", "description": "Details for subtask 2" }
  ],
  "linkType": "relates",
  "dryRun": true
})
  1. Perform the actual split
use_mcp_tool("jira-backlog-manager", "perform_split", {
  "originalTicket": "GRO-591",
  "newTickets": [
    { "summary": "Subtask 1", "description": "Details for subtask 1" },
    { "summary": "Subtask 2", "description": "Details for subtask 2" }
  ],
  "linkType": "relates",
  "dryRun": false
})
Merge Related Tickets

Dry run analysis:

use_mcp_tool("jira-backlog-manager", "merge_tickets", {
  "ticketKeys": ["GRO-867", "GRO-868"],
  "dryRun": true,
  "mergeStrategy": "smart"
})

Execute merge (duplicate-first close on secondary):

use_mcp_tool("jira-backlog-manager", "merge_tickets", {
  "ticketKeys": ["GRO-985", "GRO-987"],
  "targetTicket": "GRO-985",
  "dryRun": false
})
Advanced Analytics
// Check team workload for sprint planning
use_mcp_tool("jira-backlog-manager", "get_team_workload", {})

// Identify subject matter experts for assignment
use_mcp_tool("jira-backlog-manager", "get_team_expertise", {})

// Find blocking dependencies
use_mcp_tool("jira-backlog-manager", "get_ticket_dependencies", {})

# Analyze project performance trends
use_mcp_tool("jira-backlog-manager", "get_historical_metrics", {})

/**
 * Derive SLA and release risk from raw data + explicit policy.
 * Example policy:
 * - Finished statuses: DONE, RC, Closed, "Closed - Will not do", "Closed - Duplicate"
 * - Release blocker: unresolved AND label "blocker"
 * - SLA thresholds by priority/type (e.g., Critical Bug=1d, High Bug=3d, etc.)
 */
use_mcp_tool("jira-backlog-manager", "get_backlog_data", {})

Security

  • ✅ No hardcoded credentials: All sensitive data uses environment variables
  • ✅ Secure authentication: Uses JIRA API tokens (recommended over passwords)
  • ✅ Minimal permissions: Only requires read access to JIRA issues
  • ✅ Local execution: Runs locally, no data sent to third parties

Data Privacy

This MCP server:

  • Connects directly to your JIRA instance
  • Processes data locally on your machine
  • Does not store or transmit data to external services
  • Only accesses JIRA data you explicitly request through tool calls

Development

Project Structure

├── src/
│   ├── index.ts          # Main MCP server implementation
│   └── tools/            # Modular tool implementations
│       ├── teamWorkload.ts       # Team workload analysis
│       ├── teamExpertise.ts      # Skills and expertise mapping
│       ├── ticketDependencies.ts # Dependency analysis
│       ├── historicalMetrics.ts  # Performance metrics
│       ├── mergeTicket.ts        # Merge related tickets (dry-run and execute)
│       └── ticketSplitting.ts    # Get info and perform splits (ADF, accountId, parent preservation)
├── build/                # Compiled JavaScript output (git ignored)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

Key Dependencies

  • @modelcontextprotocol/sdk: MCP protocol implementation
  • axios: HTTP client for JIRA API calls
  • string-similarity: Text similarity analysis

Troubleshooting

Authentication Issues

  • Verify your JIRA_BASE_URL includes the full domain (e.g., https://company.atlassian.net)
  • Ensure your API token is valid and hasn't expired
  • Check that your email matches your JIRA account

Permission Issues

  • Verify you have read access to the specified JIRA project
  • Some features may require additional JIRA permissions

Connection Issues

  • Ensure your JIRA instance is accessible from your network
  • Check firewall/proxy settings if running in corporate environment

Ticket Creation 400 Errors (perform_split)

  • Common causes:
    • Required custom fields in your project (e.g., Components, Fix Version, Epic Link) are missing from the create payload
    • Invalid assignee (cannot be found or lacks access to the project)
    • Invalid description format when using Jira Cloud v3
  • This server mitigates common issues by:
    • Converting plain-text descriptions to ADF automatically
    • Resolving assignee displayName to an accountId for the v3 API
    • Preserving the original issue's parent on newly created tickets
  • If errors persist:
    • Check Jira's response details in the perform_split result (raw payload included)
    • Explicitly provide required fields (e.g., "components": ["Component A"], "fixVersions": ["2025.10"])
    • Ensure the assignee is valid in your Jira and has permission in the target project
    • Try a dry run first to validate structure, then execute without dryRun

Merge Transitions and Resolution

  • Behavior:
    • The tool prefers a transition that sets Resolution = "Duplicate" (if available in your workflow) when closing secondary tickets.
    • If no duplicate-specific transition is available, it falls back to a transition whose target status category is Done (e.g., Done/Closed/Resolved).
  • Workflow considerations:
    • Transitions and required fields vary by project/workflow. If closing fails, check available transitions in Jira and ensure your user has permission to transition and set resolution.
    • If your workflow requires a specific resolution name, ensure "Duplicate" exists or adjust your workflow accordingly.
  • Idempotency:
    • Re-running merges can append "Merged from related tickets" again to the primary’s description. If desired, add de-duplication logic to avoid repeated sections.

Contributing

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature-name
  3. Commit changes: git commit -am 'Add feature'
  4. Push to branch: git push origin feature-name
  5. Submit a Pull Request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

  • Create an issue in this repository
  • Check existing issues for similar problems
  • Provide relevant error messages and environment details