vanhoof/jiracli-mcp

jiracli-mcp

Universal JIRA MCP Server with multi-project integration, sprint insights, and comprehensive project analytics via jiracli.

✨ What This Does

This MCP server creates a powerful bridge between Claude and your JIRA instance, enabling:

• 🏃‍♂️ Sprint Insights: Progress tracking, velocity analysis, assignee workload distribution
• 📊 Multi-Project Support: Work across multiple JIRA projects with configurable defaults
• 🔍 Smart Analytics: Duplicate detection, component experts, comprehensive triage assistance
• 🎯 Board Management: List boards, analyze sprints, track completion metrics
• 🤖 Natural Language Interface: Ask questions in plain English, get structured insights

🚀 Quick Setup

Prerequisites

1. Node.js 18+ installed

   node --version  # Should show v18.0.0 or higher
   

2. jiracli installed and configured with JIRA access and .jira.yml config

   Source: jiracli on GitHub

   Choose ONE of these installation methods:

   Option A: Virtual Environment Installation (Recommended)

   • Install jiracli in a dedicated directory with Python virtual environment
   • More isolated, doesn't affect system Python packages
   • Example structure: /path/to/jiracli/ with venv/ subfolder
   • Follow the jiracli installation guide

   Option B: Global Installation

   • Install jcli globally accessible via PATH
   • Simpler setup, but affects system-wide Python packages
   • Follow the jiracli installation guide

3. Claude Desktop or Claude CLI with MCP support

   • Claude Desktop: Standard GUI application
   • Claude CLI: Use with --mcp-config flag pointing to your configuration file

Installation Steps

1. Clone and Install

git clone <this-repository>
cd jiracli-mcp
./install.sh

The installer automatically detects your jiracli setup:

• 🔍 Auto-detection: Checks if jcli is available globally
• 📋 Interactive prompts: Guides you through configuration
• ✅ Validation: Tests your jiracli installation before proceeding

You'll be prompted for:

• Default JIRA project key (e.g., PROJ, FDP, EXAMPLE)
• Board names for sprint tracking (comma-separated)
• Installation type preference (if both options are available)
• Directory paths (for virtual environment setups)

⚠️ Important: The installer validates your jiracli installation and will not proceed without a working setup.

2. Start the Server

./start-server.sh

⚠️ Important: Keep this terminal open - the server needs to stay running.

3. Configure Claude Integration

Choose one of these methods:

Option A: Claude Desktop

1. Copy the contents of the generated claude-config.json
2. Paste into Claude Desktop MCP settings:
   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
3. Restart Claude Desktop completely

Option B: Claude CLI

# Use the generated configuration directly with Claude CLI
claude --mcp-config ./claude-config.json "What boards are available?"

# Or specify an absolute path
claude --mcp-config /path/to/your/jiracli-mcp/claude-config.json "Show me sprint insights"

Generated Configuration Examples:

The installer creates a claude-config.json file with your specific paths. Here are the two possible formats:

Virtual Environment Setup:

{
  "mcpServers": {
    "jiracli-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jiracli-mcp/server.js"],
      "env": {
        "JIRA_DEFAULT_PROJECT": "EXAMPLE",
        "JIRA_BOARDS": "Board One,Board Two,Development Board",
        "JCLI_USE_GLOBAL": "false",
        "JCLI_VENV_PATH": "/absolute/path/to/jiracli/venv",
        "JCLI_WORKING_DIR": "/absolute/path/to/jiracli"
      }
    }
  }
}

Global Installation Setup:

{
  "mcpServers": {
    "jiracli-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/jiracli-mcp/server.js"],
      "env": {
        "JIRA_DEFAULT_PROJECT": "EXAMPLE",
        "JIRA_BOARDS": "Board One,Board Two,Development Board",
        "JCLI_USE_GLOBAL": "true",
        "JCLI_WORKING_DIR": "/path/to/jiracli/working/directory"
      }
    }
  }
}

4. Test the Integration

Using Claude Desktop:

• Open Claude Desktop and ask your questions directly

Using Claude CLI:

# Test sprint features
claude --mcp-config ./claude-config.json "What boards are available?"
claude --mcp-config ./claude-config.json "Show me sprints for Development Board"
claude --mcp-config ./claude-config.json "Give me insights on the active sprint"

# Test multi-project features
claude --mcp-config ./claude-config.json "What are the latest issues from MY-PROJECT?"
claude --mcp-config ./claude-config.json "Search for 'bug' across all my projects"

🗣️ Example Questions

🏃‍♂️ Sprint & Board Management

• "What boards are available in my JIRA instance?"
• "List all available boards"
• "Show me all sprints for the Development board"
• "Get board sprints for [BoardName]"
• "Give me insights on the current sprint with progress analysis"
• "What's the completion percentage and velocity in the active sprint?"
• "Show me sprint velocity and completion rates"

📊 Multi-Project Analytics

• "What are the latest PROJECT issues?"
• "Get the 10 most recent issues from PROJ2"
• "Search for authentication issues across all projects"
• "Find experts for networking components in PROJ3"

🔍 Issue Management

• "Show me details for PROJ-456"
• "Is ISSUE-123 a duplicate across projects?"
• "Who are the experts for networking components?"
• "Give me a comprehensive triage summary for EXAMPLE-1510"

🎯 Cross-Project Queries

• "Search PROJECT3 for 'certificate' issues"
• "Find experts in PROJECT4 for API components"
• "Get latest issues from PROJ but limit to 5"

🛠️ Available Tools

🆕 Sprint & Board Management

Sprint Insights Features

• Progress Tracking: Completion percentages, velocity indicators
• Assignee Analysis: Workload distribution, unassigned issues
• Status Breakdown: Issues by column/status with smart categorization
• Active Sprint Detection: Automatically focuses on current sprints
• Board Validation: Direct validation using jcli boards show

📈 Enhanced Multi-Project Tools

🔧 Configuration

Environment Variables (in .env)

The installer creates a .env file with your configuration. Here are examples:

Virtual Environment Installation:

# jiracli-mcp Configuration
JIRA_DEFAULT_PROJECT=EXAMPLE
JIRA_BOARDS=Board One,Board Two,Development Board
JCLI_USE_GLOBAL=false
JCLI_VENV_PATH=/Users/username/path/to/jiracli/venv
JCLI_WORKING_DIR=/Users/username/path/to/jiracli

# Optional settings
MCP_SERVER_PORT=3000
LOG_LEVEL=info

Global Installation:

# jiracli-mcp Configuration
JIRA_DEFAULT_PROJECT=EXAMPLE
JIRA_BOARDS=Board One,Board Two,Development Board
JCLI_USE_GLOBAL=true
JCLI_WORKING_DIR=/path/to/jiracli/working/directory

# Optional settings
MCP_SERVER_PORT=3000
LOG_LEVEL=info

Configuration Variables Explained

Multi-Project Usage Patterns

• Default Project: Uses configured default when no project specified
• Per-Query Override: "Get latest issues from PROJECT2"
• Cross-Project Search: "Search 'security' across all projects"

Board Configuration

• Optional Setup: Configure commonly used boards in JIRA_BOARDS
• Direct Validation: Each configured board is validated using jcli boards show
• Fallback Support: Can still access any board even if not configured
• Sprint Tracking: Configured boards enable faster sprint operations

🚨 Troubleshooting

Server Won't Start

1. Check Node.js version:

node --version  # Must be 18.0.0 or higher

2. Verify environment variables:

cat .env  # Check if variables are set correctly

3. Test jiracli manually:

# For virtual environment installation:
cd /your/jiracli/directory
source venv/bin/activate
jcli --version
jcli issues list --jql "project = YOUR_PROJECT" --max-issues 1

# For global installation:
jcli --version
jcli issues list --jql "project = YOUR_PROJECT" --max-issues 1

4. Check JIRA configuration:

# Ensure .jira.yml exists and is configured
ls -la ~/.jira.yml  # or check your jiracli directory

Board Validation Issues

# Test board access manually

# For virtual environment:
source /your/jiracli/path/venv/bin/activate
jcli boards list
jcli boards show "Your Board Name"

# For global installation:
jcli boards list
jcli boards show "Your Board Name"

Sprint Data Issues

# Test sprint access manually

# For virtual environment:
source /your/jiracli/path/venv/bin/activate
jcli boards sprints "YourBoardName" --json

# For global installation:
jcli boards sprints "YourBoardName" --json

Multi-Project Access

# Test project permissions
jcli issues list --jql "project = OTHERPROJECT" --max-issues 1

# List all accessible projects
jcli projects list

MCP Connection Issues

• Check server logs in the terminal running ./start-server.sh
• Verify config paths match your actual file locations
• Restart Claude Desktop completely after config changes
• Test basic connectivity: Ask "What are the latest issues?"

Common Issues & Solutions

📊 Expected Results

Sprint Insights Example

{
  "sprint_insights": [{
    "sprint_info": {
      "name": "Sprint 24",
      "state": "active",
      "start_date": "2024-01-01",
      "end_date": "2024-01-14"
    },
    "issue_analysis": {
      "total_issues": 25,
      "by_status": {
        "To Do": {"count": 8},
        "In Progress": {"count": 12}, 
        "Done": {"count": 5}
      },
      "by_assignee": {"alice": 8, "bob": 12},
      "unassigned_count": 5
    },
    "progress_metrics": {
      "completion_percentage": 20,
      "velocity_indicators": {
        "done_issues": 5,
        "in_progress_issues": 12,
        "todo_issues": 8
      }
    }
  }]
}

📁 Project Structure

jiracli-mcp/
├── server.js                    # Enhanced MCP server
├── package.json                 # Node.js dependencies
├── install.sh                   # Interactive installer
├── start-server.sh              # Server startup script
├── claude-config.json           # Generated MCP config (created by installer)
├── claude-desktop-config.json   # Template for config generation
├── config.example.json          # Virtual environment setup template
├── config-global.example.json   # Global installation setup template
├── .env                         # Environment configuration (created by installer)
└── README.md                   # This comprehensive guide

🎯 For Other Users

Step-by-Step Setup for New Users

1. Install Prerequisites

# Install Node.js 18+ (if not already installed)
# Visit: https://nodejs.org

# Verify installation
node --version
npm --version

2. Set up jiracli (Choose ONE method)

Option A: Virtual Environment (Recommended)

# Create dedicated directory
mkdir ~/jiracli
cd ~/jiracli

# Create Python virtual environment
python3 -m venv venv
source venv/bin/activate

# Install and configure jiracli - follow the official guide:
# https://github.com/apconole/jiracli#installation

Option B: Global Installation

# Install and configure jiracli globally - follow the official guide:
# https://github.com/apconole/jiracli#installation

3. Clone and Install jiracli-mcp

git clone <this-repository>
cd jiracli-mcp
./install.sh

4. Follow installer prompts

• Provide your JIRA project key
• Enter board names for sprint tracking
• Choose installation type (auto-detected)
• Verify paths and configuration

5. Configure Claude Integration

• For Claude Desktop: Copy contents of generated claude-config.json to MCP settings, restart Claude Desktop
• For Claude CLI: Use claude --mcp-config ./claude-config.json "your question" directly

Note: The installer validates everything and provides specific error messages if something isn't working.

Advanced Configuration

Manual Environment Setup

If you need to manually configure (instead of using the installer):

1. Copy template files:

   • Virtual env: cp config.example.json claude-config.json
   • Global install: cp config-global.example.json claude-config.json

2. Edit paths in claude-config.json

3. Create .env file with your settings (see Configuration section above)

Environment Variables Reference

• JIRA_DEFAULT_PROJECT: Your primary JIRA project key
• JIRA_BOARDS: Comma-separated list of board names (optional)
• JCLI_USE_GLOBAL: Set to true for global jcli, false for virtual env
• JCLI_VENV_PATH: Path to virtual environment (venv installs only)
• JCLI_WORKING_DIR: jiracli working directory
• MCP_SERVER_PORT: Server port (optional, default: 3000)
• LOG_LEVEL: Logging verbosity (optional, default: info)

🎉 Features

• ✅ Multi-Project Support - Work with any JIRA project
• ✅ Sprint Insights - Comprehensive sprint analysis with velocity tracking
• ✅ Board Management - List and analyze boards across your instance
• ✅ Board Validation - Direct validation using jcli boards show for accuracy
• ✅ Progress Tracking - Completion percentages and bottleneck identification
• ✅ Dual Installation Support - Works with both global and virtual environment jiracli
• ✅ Cross-Project Analytics - Search and analyze across multiple projects
• ✅ Interactive Installer - Auto-detection and guided setup
• ✅ Robust Validation - Configuration checking and error handling

🚀 Your JIRA workflow is now AI-powered with comprehensive sprint insights!

Ask Claude questions like: "What boards are available and show me sprint insights for the most active one?"