Jira Pilot ✈️

The AI-Powered Jira CLI and MCP Server for Humans and Agents.

jira-pilot is a next-generation CLI that combines traditional developer tools with modern AI capabilities.

• For Humans: A beautiful, interactive CLI to manage issues, sprints, boards, and code. Now with AI Code Reviews, Epic Planning, Daily Standups, and Natural Language JQL.
• For Agents: A fully compliant Model Context Protocol (MCP) server with 14 tools that lets AI assistants (like Claude Desktop, Cursor, or Gemini) interact with your Jira instance safely.

---

Features at a Glance

👤 Human-Centric Features

Feature	Description
Issue Management	Create, edit, view, list, transition, assign, and comment on issues
Work & Time	New: Log work (2h 30m), manage sprints (start/complete), and subtasks
Developer Tools	New: Open PRs, save local filters, git branch integration
Power Tools	New: Bulk assign, bulk label, bulk transition matching JQL
Advanced Data	New: Upload attachments, manage custom fields by alias
AI Copilot	Summarize, draft descriptions, suggest actions, review code, plan epics, standup reports
Interactive Wizards	Step-by-step prompts with enquirer — no flags required
Rich Visualization	Dashboard overview, spinners, and formatted output
Export	Output to JSON or Markdown files, pipeable JSON output

🤖 Agentic Features (MCP)

Feature	Description
14 MCP Tools	list_issues, get_issue, create_issue, update_issue, transition_issue, assign_issue, add_comment, add_worklog, create_subtask, add_attachment, search_users, myself, list_projects, list_sprints
LLM-Optimized	Clean, structured JSON responses for efficient token usage
Stdio Transport	Standard MCP stdio server — works with any MCP client

---

🚀 Installation

Prerequisites

• Node.js 20.0.0 or higher

Global Install (Recommended)

npm install -g jira-pilot

After installing, the jira command is available globally.

---

⚙️ Configuration

Before using the tool, set up your credentials. You can get an API Token from Atlassian Account Settings.

Initial Setup

jira config setup

You will be prompted for:

1. Jira Site URL — e.g., https://your-company.atlassian.net
2. Email — Your Atlassian account email
3. API Token — The token you generated from Atlassian
4. Enable AI — Toggle AI features on/off
5. AI Provider — Choose between openai, gemini, or anthropic
6. AI API Key — Your API key for the selected provider

Profiles & Management

Manage credentials for multiple environments (e.g., Work vs. Personal, Prod vs. Dev).

jira config view              # Show current configuration (keys are masked)
jira config save work         # Save current creds as profile 'work'
jira config use personal      # Switch to profile 'personal'
jira config profiles          # List all saved profiles
jira config delete-profile work
jira config clear             # Remove all stored credentials

Custom Field Aliases

Define aliases for custom field IDs to make commands easier:

jira config field set points customfield_10011
jira config field list

---

✨ Interactive Experience

Jira Pilot is designed to be fully interactive. You don't need to remember complex flags.

Just run the command, and we'll guide you:

1. Selection: Use arrow keys ↑ ↓ to navigate lists (Projects, Issue Types, Priorities).
2. Filtering: Start typing to filter long lists (e.g., finding a specific assignee).
3. Wizards: Complex flows like creating an issue are broken down into simple steps.
4. Confirmation: Destructive actions prompt for confirmation (y/N).

Example:

jira issue create
? Select Project: PROJ - My Project
? Select Issue Type: Bug
? Summary: Login page crashes
? Priority: High
? Assignee: Me

---

🖥️ Text User Interface (TUI)

Experience Jira in a persistent, interactive terminal interface.

jira tui

Key Features:

• Dashboard: Overview of your assigned work.
• Issue Navigator: Browse, filter, and view issues.
• Kanban Boards: Visualize and manage work on Agile boards.
• Interactive: Use arrow keys to navigate rows and columns.

Navigation Shortcuts:

• ← / → : Switch Tabs (Dashboard, Issues, Boards) or Board Columns
• ↑ / ↓ : Navigate Lists
• Enter : Select / View Details
• Esc / b : Back
• q : Quit

---

📊 My Dashboard

Start your day with a high-level overview of what's on your plate.

jira dashboard

What you'll see:

• 👋 Welcome Message: Personalized greeting.
• 🔥 High Priority: Issues assigned to you that need immediate attention.
• 📋 Recent Activity: Your recently viewed or updated issues.
• 🚀 Sprint Status: (If applicable) Active sprint progress.

---

📖 Usage Guide

📋 Issue Management

List Issues

# List issues assigned to you in active sprints (interactive)
jira issue list

# List with custom JQL
jira issue list --jql "project = PROJ AND priority = High"

# Filter by project, assignee, or status via flags
jira issue list --project PROJ --assignee "john.doe" --status "In Progress"

# Limit results
jira issue list --limit 20

# Natural Language JQL (AI)
jira issue list --ask "high priority bugs assigned to me"

# Export results to file
jira issue list --export json    # Creates issues-TIMESTAMP.json
jira issue list --export md      # Creates issues-TIMESTAMP.md

# Pipeable JSON output (to stdout)
jira issue list --output json | jq .

Search Issues

Quick text search using JQL text ~ "query":

jira issue search "login bug"
jira issue search "error 500" --project PROJ

View Issue Details

jira issue view PROJ-123

Displays: summary, status, priority, assignee, description, components, labels, dates, versions, and recent comments.

Create Issue

# Interactive wizard (recommended)
jira issue create

# Non-interactive with flags for speed
jira issue create -p PROJ -s "Fix login bug"
jira issue create -p PROJ -t Bug -s "Crash on save" --priority High
jira issue create -p PROJ -t Story -s "Add dark mode" -d "Users want a dark theme" -a me

# With Custom Fields (using Alias or ID)
jira issue create -p PROJ -s "Story" --custom "points=5" --custom "customfield_10022=DevOps"

Edit Issue

# Interactive Field Picker
jira issue edit PROJ-123

# Quick Edits
jira issue edit PROJ-123 -s "New Summary" --priority High
jira issue edit PROJ-123 -d "New description"
jira issue edit PROJ-123 --custom "points=8"

Transition Issue Status

# Interactive — shows available transitions
jira issue transition PROJ-123

# Direct — specify target status
jira issue transition PROJ-123 --status "In Progress"
jira issue transition PROJ-123 -s Done

Assign / Reassign

# Interactive — choose Myself, Unassign, or Search
jira issue assign PROJ-123

# Quick assign
jira issue assign PROJ-123 -a me       # Assign to yourself
jira issue assign PROJ-123 -a none     # Unassign

Add Comment

# Interactive — prompts for comment text
jira issue comment PROJ-123

# Inline comment
jira issue comment PROJ-123 -m "Fixed in latest build"

Other Actions

# Link Issues
jira issue link PROJ-123 PROJ-456 -t Blocks

# Watchers
jira issue watch PROJ-123
jira issue unwatch PROJ-123

# Attachments
jira issue attach PROJ-123 ./logs/server.log

---

⏱️ Work & Time

Worklogs

Track time naturally against issues.

# Add worklog
jira issue worklog add PROJ-123 2h "Researching API"
jira issue worklog add PROJ-123 30m "Daily standup"
jira issue worklog add PROJ-123 1d "Implementation"

# List worklogs
jira issue worklog list PROJ-123

Subtasks

# Interactive subtask creation
jira issue subtask PARENT-123

# Quick subtask
jira issue subtask PARENT-123 -s "Implement backend logic" --assignee me

Sprint Management

Manage your Agile boards directly.

# List sprints
jira sprint list --board "My Board"
jira sprint list --board 5 --state active

# List issues in active sprint
jira sprint issues --board 5

# Start/Complete Sprints
jira sprint start 123 --start-date 2023-10-01 --end-date 2023-10-15
jira sprint complete 123

---

👨‍💻 Developer Workflow

Pull Requests

Open a GitHub PR with title and body pre-filled from the Jira issue.

jira issue pr PROJ-123
# Requires 'gh' CLI to be installed and authenticated

Git Integration

Create feature branches automatically named from the issue summary.

jira git branch PROJ-123
# Creates: feature/PROJ-123-issue-summary-slug

Saved Filters

Save complex JQL queries locally for quick access.

# Save a filter
jira filter save "My Bugs" "assignee = currentUser() AND issuetype = Bug AND status != Done"

# List saved filters
jira filter list

# Use a saved filter
jira issue list --filter "My Bugs"

# Delete a filter
jira filter delete "My Bugs"

---

⚡ Power Tools (Bulk Actions)

Perform actions on multiple issues matching a JQL query. Great for cleanups or mass updates.

Bulk Transition

Move multiple issues to a new status.

jira bulk transition -j "project = PROJ AND status = 'To Do'" -s "In Progress"
# Optional: -y to skip confirmation

Bulk Assign

Assign a set of issues to a user.

jira bulk assign -j "priority = High AND assignee is EMPTY" --assignee me

Bulk Label

Add or remove labels from a set of issues.

jira bulk label -j "fixVersion = 1.0" --add "release-candidate" --remove "wip"

---

📂 Projects & Boards

List Projects

jira project list
# Displays: project key, name, lead, and style in a formatted table.

List Boards

# List all boards
jira board list

# Filter by project
jira board list -p PROJ

# Filter by type
jira board list -t scrum
jira board list -t kanban

---

🤖 AI Features

Requires: AI enabled in config setup.

Summarize an Issue

Get an AI-generated TL;DR of long issue threads with comments:

jira ai summarize PROJ-123

Draft an Issue Description

Generate a structured issue description from rough notes or bullet points:

# Interactive — prompts for your notes
jira ai draft

# Inline with issue type context
jira ai draft -i "login fails, returns 500, only on mobile" -t bug
jira ai draft -i "add dark mode toggle to settings" -t story

Suggest Next Actions

Analyze an issue and get AI-powered suggestions for what to do next:

jira ai suggest PROJ-123

Returns: Immediate Next Action, Potential Blockers, Suggested Status Transition, and Recommendations.

AI Code Review

Analyze linked PRs/code changes against issue requirements:

jira ai review PROJ-123

Requires githubToken in config.

AI Epic Planning

Break down an Epic into child Stories/Tasks and bulk create them:

jira ai plan EPIC-123    # Interactive selection of proposed tasks

AI Standup Report

Generate a daily standup based on your recent activity:

jira ai standup

Outputs: Yesterday, Today, Blockers.

---

🧠 Using with AI Agents (MCP)

jira-pilot implements the Model Context Protocol (MCP), making it plug-and-play for AI assistants.

Starting the MCP Server

jira mcp

Available MCP Tools (14)

Everything you need to build a fully autonomous Jira agent:

1. jira_list_issues: Search via JQL (supports limit)
2. jira_get_issue: Get full details
3. jira_create_issue: Create new issue (ADF support)
4. jira_update_issue: Update summary, desc, priority, assignee
5. jira_transition_issue: Change status
6. jira_assign_issue: Change assignee
7. jira_add_comment: Add comment
8. jira_add_worklog: Log time
9. jira_create_subtask: Create subtask
10. jira_add_attachment: Upload file (absolute path)
11. jira_search_users: Search for users
12. jira_myself: Get current user details
13. jira_list_projects: List accessible projects
14. jira_list_sprints: List sprints for a board

Agent Configuration (Claude Desktop)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "jira-pilot", "mcp"]
    }
  }
}

VS Code / Cursor Configuration

Add to your .vscode/mcp.json or equivalent:

{
  "servers": {
    "jira-pilot": {
      "command": "jira",
      "args": ["mcp"]
    }
  }
}

📝 Prompts

Pre-defined templates to help LLMs interact with Jira effectively.

Prompt	Arguments	Description
jira-assist	None	System prompt that teaches the LLM how to use Jira Pilot tools best.
jira-summarize-issue	issueKey	Fetches an issue and instructs the LLM to provide a concise summary.

📦 Resources

Direct access to Jira data as context.

URI	Description
jira://myself	Details of the currently authenticated user (excluding sensitive PII).
jira://projects	List of all accessible Jira projects.

🔍 Verification

You can verify the MCP server implementation using the official inspector:

# If running fro source
npx @modelcontextprotocol/inspector node dist/bin/jira.js mcp

# If installed globally (or via npx)
npx @modelcontextprotocol/inspector npx -y jira-pilot mcp

---

📦 CLI Command Reference

Run jira help or jira [command] help to see all options.

jira [command]

Commands:
  config           Configure Jira credentials & profiles
  issue            Manage Jira issues
  project          Manage Jira projects
  board            Manage Jira boards
  sprint           Manage Sprints
  bulk             Bulk operations on Jira issues
  dashboard        Show a quick overview of your Jira activity
  git              Git integration for Jira
  ai               AI Helper commands
  mcp              Start MCP Agent Server (Stdio)

---

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for details on how to submit a pull request and set up your development environment.

Please note that this project is released with a Contributor Code of Conduct. By participating in this project you agree to abide by its terms.

🛡️ Security

If you discover a security vulnerability within this project, please check SECURITY.md for our reporting policy.

📄 License

ISC