Jira Automation CLI & MCP Server

A command-line tool and MCP (Model Context Protocol) server for automating the creation of Jira epics, stories, and tasks from JSON files.

Installation

Option 1: Install via npx (Recommended)

# Run directly without installation
npx jira-automation-cli --help

# Or install globally
npm install -g jira-automation-cli

Option 2: Install from source

# Clone the repository
git clone https://github.com/pradipparmar/jira-automation.git
cd jira-automation

# Install dependencies
npm install

# Build the project
npm run build

# Run the CLI
npm start -- --help

Configuration

Create a .env file in your project root with your Jira credentials and project settings. You can copy .env.example as a template:

JIRA_URL=https://your-domain.atlassian.net
[email protected]
JIRA_API_TOKEN=your-api-token
JIRA_EPIC_LINK_FIELD=customfield_10014
JIRA_STORY_POINTS_FIELD=customfield_10043

Note: Do not commit your .env file with real credentials to version control. Use .env.example as a reference for others.

Usage

CLI Mode

# Process all items (with environment variables)
jira-automation process -f ./linkinbio --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Process all items (with direct values)
jira-automation process -f ./linkinbio --jira-url https://your-domain.atlassian.net --jira-email [email protected] --jira-api-token your-api-token --epic-link-field customfield_10014 --story-points-field customfield_10043

# Perform a dry run
jira-automation process -f ./linkinbio --dry-run --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Force recreation of existing items
jira-automation process -f ./linkinbio --force --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Skip specific item types
jira-automation process -f ./linkinbio --skip-epics --skip-stories --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Continue processing on error
jira-automation process -f ./linkinbio --continue-on-error --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Create a new sprint
jira-automation create-sprints --board 123 --jira-url $JIRA_URL --jira-email $JIRA_EMAIL --jira-api-token $JIRA_API_TOKEN --epic-link-field $JIRA_EPIC_LINK_FIELD --story-points-field $JIRA_STORY_POINTS_FIELD

# Validate folder structure
jira-automation validate -f ./linkinbio

# Validate and create missing structure
jira-automation validate-and-create -f ./linkinbio

# Reset all Jira IDs
jira-automation reset-ids -f ./linkinbio

# Start MCP server
jira-automation mcp-server

Note: The CLI automatically loads environment variables from .env file, but you can still override them with command-line arguments.

MCP Server Mode

The Jira automation is also available as an MCP server, providing programmatic access to all CLI features.

Starting the MCP Server

# Start the MCP server
jira-automation mcp-server

# Or run directly
npx jira-automation-cli mcp-server

# The server will listen on port 4333 by default

Available MCP Tools

The MCP server exposes the following tools:

• jira_process_items: Process Jira items from a folder structure
• jira_validate_structure: Validate folder structure without processing
• jira_validate_and_create_structure: Validate and create missing folder structure
• jira_reset_ids: Reset all Jira IDs to null in JSON files
• jira_create_sprint: Create a new sprint based on existing sprints
• jira_create_epic: Create a single epic
• jira_create_story: Create a single story
• jira_create_task: Create a single task

Using with MCP Clients

You can use the MCP server with any MCP-compatible client. The server accepts the same parameters as the CLI commands but in a programmatic format.

Example MCP tool call:

{
  "name": "jira_process_items",
  "arguments": {
    "folderPath": "./linkinbio",
    "dryRun": false,
    "force": false,
    "skipEpics": false,
    "skipStories": false,
    "skipTasks": false,
    "continueOnError": false,
    "jiraUrl": "https://your-domain.atlassian.net",
    "jiraEmail": "[email protected]",
    "jiraApiToken": "your-api-token",
    "epicLinkField": "customfield_10014",
    "storyPointsField": "customfield_10043"
  }
}

File Structure

Create a folder (e.g., "vritix") with the following structure:

vritix/
├── epic.json
├── Requirement.md
└── [epic_name]/
    ├── story.json
    └── [story_name]/
        └── tasks.json

Folder Naming Rules

• Special Characters: All special characters are removed from folder names
• Spaces: All spaces are replaced with underscores
• Case: All folder names are converted to lowercase
• Examples:
  • "Authentication & Authorization System" → "authentication_authorization_system"
  • "User Management (v2)" → "user_management_v2"
  • "API Integration & Testing" → "api_integration_testing"

epic.json

{
  "projectKey": "VRITIX",
  "epics": [
    {
      "name": "Authentication System",
      "description": "Implement secure authentication and authorization system",
      "jiraId": "VRITIX-1",
      "update": true
    },
    {
      "name": "User Management",
      "description": "Implement user management features",
      "jiraId": null,
      "update": false
    }
  ]
}

story.json

{
  "stories": [
    {
      "name": "Create New Admin",
      "description": "As a system administrator, I want to create new admin users",
      "storyPoints": 5,
      "jiraId": null,
      "update": false,
      "acceptanceCriteria": [
        "Admin can create new admin users",
        "New admin users must have valid email addresses",
        "New admin users must have strong passwords"
      ],
      "tests": [
        "Test admin creation with valid data",
        "Test admin creation with invalid email",
        "Test admin creation with weak password"
      ],
      "steps": [
        "Create admin creation form",
        "Implement email validation",
        "Implement password strength validation",
        "Add admin user to database"
      ]
    }
  ]
}

tasks.json

{
  "tasks": [
    {
      "name": "Implement End-to-End User Registration API",
      "description": "Develop the complete backend for user registration, including model, API endpoint, business logic, validation, integration, and unit tests.",
      "storyPoints": 5,
      "jiraId": null,
      "labels": ["backend", "api", "validation"]
    },
    {
      "name": "Implement User Registration UI",
      "description": "Build and integrate the user registration form, handle validation, error states, and connect to the backend API.",
      "storyPoints": 3,
      "jiraId": null,
      "labels": ["frontend", "ui"]
    }
  ]
}

CLI Options

• -f, --folder <path>: Path to the folder containing Jira items (required)
• --dry-run: Perform a dry run without creating items
• --force: Force recreation of existing items
• --skip-epics: Skip processing epics
• --skip-stories: Skip processing stories
• --skip-tasks: Skip processing tasks
• --continue-on-error: Continue processing on error

Development

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Run type checking
npm run type-check

# Run all validations
npm run validate

# Start MCP server in development mode
npm run mcp-server

License

ISC

Task Guidelines

• Backend tasks should cover the entire end-to-end API flow in a single task. This includes model creation, business logic, validation, integration, and testing. Do not split these into separate tasks for model, API, or testing.
• UI tasks should cover all required UI changes, integration, and implementation for the feature or story. Do not split into separate tasks for component creation, integration, or UI testing.
• Avoid over-dividing tasks. Each task should represent a meaningful, manageable unit of work that delivers value and can be tracked end-to-end.