jira.js - JavaScript/TypeScript Client for Jira

jira.js - JavaScript/TypeScript Client for Jira

Research Date: 2026-02-20 Source URL: https://mrrefactoring.github.io/jira.js/ GitHub Repository: https://github.com/MrRefactoring/jira.js npm Package: https://www.npmjs.com/package/jira.js Version at Research: v4.0.1 License: MIT

Overview

jira.js is a comprehensive JavaScript and TypeScript client library for Atlassian Jira's REST API. It provides full coverage of Jira Cloud, Jira Server, and Jira Data Center APIs with strong TypeScript typing, promise-based async/await support, and automatic request/response handling. The library abstracts the complexity of Jira's extensive API surface into a clean, intuitive interface.

Core Value Proposition: Enable developers to integrate Jira functionality into applications with type-safe, well-documented methods covering all Jira APIs (Core, Agile, ServiceDesk) without manual API endpoint construction.

Problem Addressed

Key Statistics

Key Features

1. Complete API Coverage

Jira Platform REST API v3 (Cloud):

• Issues and issue fields
• Projects and project components
• Users and groups
• Workflows and workflow schemes
• Permissions and permission schemes
• Dashboards and filters
• Application properties
• Audit logs

Jira Agile (Jira Software) API:

• Boards (Scrum and Kanban)
• Sprints and sprint management
• Backlogs
• Epics
• Estimates and velocity
• Reports

Jira Service Management API:

• Service desks and queues
• Customer requests
• SLA tracking
• Organizations
• Knowledge base articles

Jira Server/Data Center APIs:

• Legacy API v2 support
• Server-specific endpoints
• Data Center clustering features

2. Type Safety

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'user@example.com',
      apiToken: 'your-api-token'
    }
  }
});

// Fully typed responses
const issue = await client.issues.getIssue({ issueIdOrKey: 'PROJECT-123' });
// issue.fields is typed with Jira field types
console.log(issue.fields.summary); // TypeScript knows this is a string

3. Multiple Authentication Methods

API Token (Cloud - Recommended):

authentication: {
  basic: {
    email: 'user@example.com',
    apiToken: 'ATATT3xFfGF0...'
  }
}

OAuth 2.0 (Cloud):

authentication: {
  oauth2: {
    accessToken: 'your-access-token'
  }
}

Personal Access Token (Server/Data Center):

authentication: {
  personalAccessToken: 'your-pat-token'
}

Basic Authentication (Server/Data Center - Legacy):

authentication: {
  basic: {
    username: 'admin',
    password: 'admin-password'
  }
}

4. Version-Specific Clients

// Jira Cloud (API v3)
import { Version3Client } from 'jira.js';
const cloudClient = new Version3Client({ /* config */ });

// Jira Cloud (API v2)
import { Version2Client } from 'jira.js';
const v2Client = new Version2Client({ /* config */ });

// Agile API
import { AgileClient } from 'jira.js';
const agileClient = new AgileClient({ /* config */ });

5. Pagination Support

// Automatic pagination handling
const issues = await client.issueSearch.searchForIssuesUsingJql({
  jql: 'project = PROJ',
  maxResults: 50,
  startAt: 0
});

// Paginate through all results
let startAt = 0;
const maxResults = 50;
let allIssues = [];

while (true) {
  const response = await client.issueSearch.searchForIssuesUsingJql({
    jql: 'project = PROJ',
    maxResults,
    startAt
  });

  allIssues.push(...response.issues);

  if (response.issues.length < maxResults) break;
  startAt += maxResults;
}

6. Middleware Support

// Request/response interceptors
const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: { /* ... */ },
  middlewares: [
    {
      onRequest: (config) => {
        console.log('Request:', config);
        return config;
      },
      onResponse: (response) => {
        console.log('Response:', response);
        return response;
      },
      onError: (error) => {
        console.error('Error:', error);
        throw error;
      }
    }
  ]
});

7. File Upload/Download

// Upload attachment to issue
import fs from 'fs';

await client.issueAttachments.addAttachment({
  issueIdOrKey: 'PROJECT-123',
  attachment: fs.createReadStream('./document.pdf')
});

// Download attachment
const attachment = await client.issueAttachments.getAttachment({
  id: '10000'
});

Technical Architecture

Application Code
      |
      v
+------------------------------------------+
|           jira.js Client                 |
|  +------------------------------------+  |
|  |      Version-Specific Client       |  |
|  |  - Version3Client (Cloud v3)       |  |
|  |  - Version2Client (Cloud v2)       |  |
|  |  - AgileClient (Agile API)         |  |
|  |  - ServiceDeskClient (SM API)      |  |
|  +------------------------------------+  |
|                   |                       |
|                   v                       |
|  +------------------------------------+  |
|  |      Authentication Layer          |  |
|  |  - Basic (email + token)           |  |
|  |  - OAuth 2.0                       |  |
|  |  - Personal Access Token           |  |
|  |  - Token refresh handling          |  |
|  +------------------------------------+  |
|                   |                       |
|                   v                       |
|  +------------------------------------+  |
|  |      Request Builder               |  |
|  |  - URL construction                |  |
|  |  - Parameter validation            |  |
|  |  - Body serialization              |  |
|  |  - Multipart form data             |  |
|  +------------------------------------+  |
|                   |                       |
|                   v                       |
|  +------------------------------------+  |
|  |      Middleware Pipeline           |  |
|  |  - Request interceptors            |  |
|  |  - Response interceptors           |  |
|  |  - Error handlers                  |  |
|  |  - Retry logic                     |  |
|  +------------------------------------+  |
|                   |                       |
|                   v                       |
|  +------------------------------------+  |
|  |      HTTP Client (Axios)           |  |
|  |  - Connection pooling              |  |
|  |  - Timeout handling                |  |
|  |  - Automatic retries               |  |
|  +------------------------------------+  |
+------------------------------------------+
      |
      v
Jira REST API (Cloud/Server/Data Center)

Installation & Usage

Installation

# npm
npm install jira.js

# yarn
yarn add jira.js

# pnpm
pnpm add jira.js

Basic Usage - Jira Cloud

import { Version3Client } from 'jira.js';

const client = new Version3Client({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your-email@example.com',
      apiToken: 'your-api-token'
    }
  }
});

// Get issue
const issue = await client.issues.getIssue({
  issueIdOrKey: 'PROJECT-123'
});

console.log(issue.fields.summary);
console.log(issue.fields.status.name);

Create Issue

const newIssue = await client.issues.createIssue({
  fields: {
    project: {
      key: 'PROJ'
    },
    summary: 'Issue created via jira.js',
    description: 'This is a test issue',
    issuetype: {
      name: 'Task'
    },
    priority: {
      name: 'Medium'
    }
  }
});

console.log(`Created issue: ${newIssue.key}`);

Update Issue

await client.issues.editIssue({
  issueIdOrKey: 'PROJECT-123',
  fields: {
    summary: 'Updated summary',
    description: 'Updated description'
  }
});

Add Comment

await client.issueComments.addComment({
  issueIdOrKey: 'PROJECT-123',
  body: {
    type: 'doc',
    version: 1,
    content: [
      {
        type: 'paragraph',
        content: [
          {
            type: 'text',
            text: 'This is a comment added via jira.js'
          }
        ]
      }
    ]
  }
});

Search Issues (JQL)

const searchResults = await client.issueSearch.searchForIssuesUsingJql({
  jql: 'project = PROJ AND status = "In Progress"',
  fields: ['summary', 'status', 'assignee'],
  maxResults: 50
});

searchResults.issues.forEach(issue => {
  console.log(`${issue.key}: ${issue.fields.summary}`);
});

Agile API - Sprint Management

import { AgileClient } from 'jira.js';

const agileClient = new AgileClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your-email@example.com',
      apiToken: 'your-api-token'
    }
  }
});

// Get board
const board = await agileClient.board.getBoard({ boardId: 1 });

// Get active sprint
const sprints = await agileClient.board.getAllSprints({
  boardId: 1,
  state: 'active'
});

// Get sprint issues
const sprintIssues = await agileClient.sprint.getIssuesForSprint({
  sprintId: sprints.values[0].id
});

Service Desk API

import { ServiceDeskClient } from 'jira.js';

const serviceDeskClient = new ServiceDeskClient({
  host: 'https://your-domain.atlassian.net',
  authentication: {
    basic: {
      email: 'your-email@example.com',
      apiToken: 'your-api-token'
    }
  }
});

// Get service desks
const serviceDesks = await serviceDeskClient.servicedesk.getServiceDesks();

// Create customer request
const request = await serviceDeskClient.request.createCustomerRequest({
  serviceDeskId: '1',
  requestTypeId: '10',
  requestFieldValues: {
    summary: 'Need help with account',
    description: 'I cannot access my account'
  }
});

Relevance to Claude Code Development

Applications

1. AI Agent Task Integration: Agents can create, update, and track Jira issues programmatically for project management workflows
2. Automated Issue Creation: Claude Code could create Jira issues from conversation context (bugs found, features discussed, technical debt identified)
3. Context Gathering: Pull Jira issue context into Claude Code sessions to understand current project state
4. Workflow Automation: Automate transitions, assignments, and status updates based on code analysis or completion
5. Sprint Planning: AI-assisted sprint planning by analyzing issue complexity, dependencies, and team capacity

Patterns Worth Adopting

1. Namespace Organization: jira.js organizes 500+ methods into logical namespaces (issues, projects, users) - applicable to large skill libraries
2. Version-Specific Clients: Separate clients for API versions prevents breaking changes - pattern for Claude Code plugin versioning
3. TypeScript-First Design: Generated types from API specs ensure accuracy - could generate skill types from YAML frontmatter
4. Middleware Pattern: Request/response interceptors enable logging, retries, error handling - applicable to MCP tool chains
5. Authentication Abstraction: Single config supports multiple auth methods - pattern for multi-provider MCP servers

Integration Opportunities

1. Jira MCP Server: Create MCP server using jira.js for native Jira integration in Claude Code
2. Issue Tracking Skill: Skill that uses jira.js to link code changes to Jira issues automatically
3. Project Context Tool: Tool that fetches current sprint/backlog to inform AI about project priorities
4. Automated Documentation: Link generated docs to Jira epics/stories
5. Quality Gate Integration: Create Jira issues for failed tests, linting errors, or security vulnerabilities

MCP Server Implementation Pattern

// Example MCP server for Jira using jira.js
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { Version3Client } from 'jira.js';

const jiraClient = new Version3Client({
  host: process.env.JIRA_HOST,
  authentication: {
    basic: {
      email: process.env.JIRA_EMAIL,
      apiToken: process.env.JIRA_API_TOKEN
    }
  }
});

const server = new Server({
  name: 'jira-mcp',
  version: '1.0.0'
}, {
  capabilities: {
    tools: {}
  }
});

server.setRequestHandler('tools/list', async () => ({
  tools: [
    {
      name: 'jira_get_issue',
      description: 'Fetch Jira issue details by key or ID',
      inputSchema: {
        type: 'object',
        properties: {
          issueKey: { type: 'string', description: 'Issue key (e.g., PROJ-123)' }
        },
        required: ['issueKey']
      }
    },
    {
      name: 'jira_create_issue',
      description: 'Create new Jira issue',
      inputSchema: {
        type: 'object',
        properties: {
          project: { type: 'string', description: 'Project key' },
          summary: { type: 'string', description: 'Issue summary' },
          issueType: { type: 'string', description: 'Issue type (Task, Bug, Story)' }
        },
        required: ['project', 'summary', 'issueType']
      }
    },
    {
      name: 'jira_search_issues',
      description: 'Search issues using JQL',
      inputSchema: {
        type: 'object',
        properties: {
          jql: { type: 'string', description: 'JQL query string' },
          maxResults: { type: 'number', description: 'Maximum results', default: 50 }
        },
        required: ['jql']
      }
    }
  ]
}));

server.setRequestHandler('tools/call', async (request) => {
  switch (request.params.name) {
    case 'jira_get_issue': {
      const issue = await jiraClient.issues.getIssue({
        issueIdOrKey: request.params.arguments.issueKey
      });
      return {
        content: [{
          type: 'text',
          text: JSON.stringify(issue, null, 2)
        }]
      };
    }
    // ... other tool implementations
  }
});

Key Insight

jira.js demonstrates that comprehensive API client libraries can make complex external services accessible to AI agents. The type-safe, well-documented interface enables AI systems to interact with Jira without hallucinating API endpoints or parameters. This pattern applies to any external service integration: strong typing + clear documentation + logical organization = reliable AI tool usage.

References

1. Official Documentation: https://mrrefactoring.github.io/jira.js/ (accessed 2026-02-20)
2. GitHub Repository: https://github.com/MrRefactoring/jira.js (accessed 2026-02-20)
3. npm Package: https://www.npmjs.com/package/jira.js (accessed 2026-02-20)
4. Jira Cloud REST API Documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v3/intro/ (accessed 2026-02-20)
5. Jira Agile REST API Documentation: https://developer.atlassian.com/cloud/jira/software/rest/intro/ (accessed 2026-02-20)
6. Jira Service Management API: https://developer.atlassian.com/cloud/jira/service-desk/rest/intro/ (accessed 2026-02-20)

Related Tools

Freshness Tracking

Change Detection Indicators:

• Monitor npm for new version releases (v4.x active development)
• Check GitHub releases for API coverage updates
• Watch Atlassian Jira API changelog for new endpoints
• Track TypeScript type definition updates
• Review documentation for new authentication methods
• Monitor for Jira Cloud vs Server/Data Center API divergence