Jira Cloud MCP Server

A production-ready, clean, and modular Model Context Protocol (MCP) server that enables LLMs to communicate directly with the official Jira Cloud REST API v3 using standard STDIO transport. Built using TypeScript strict mode and axios.

Features

• jira_get_create_metadata: Inspect projects, issue types, field requirements, and custom field IDs (customfield_XXXXX).
• jira_get_create_issue_meta_fields: Fetch the field configurations and custom fields for a specific project and issue type when creating an issue (granular and high-performance alternative).
• jira_get_project_issue_types: Fetch all issue types available for a specific project, including their IDs (used to retrieve metadata fields).
• jira_create_issue: Create new tickets, automatically converting plain text descriptions into the required Jira Cloud Atlassian Document Format (ADF). Supports optional custom fields.
• jira_get_issue: Fetch complete details for a ticket using its ID or Key.
• jira_search_jql: Query issues using Jira Query Language (JQL) with customizable limits.
• jira_find_users: Search for Jira users to retrieve their unique accountId (required for assigning issues or setting user fields in Jira v3).
• jira_get_transitions: Retrieve the workflow transitions and statuses available for a specific issue, along with their transitionIds.
• jira_transition_issue: Transition an issue to a new status (e.g., "Done", "QA") using a transition ID.

---

Configuration & Authentication

The server supports both Jira Data Center (PAT Bearer Token) and Jira Cloud (Basic Auth).

Jira Data Center (PAT Authentication - Recommended)

Define these environment variables:

Environment Variable	Description	Example
JIRA_HOST	The root URL of your Jira Data Center instance	https://jira.yourcompany.com
JIRA_API_TOKEN	Your Personal Access Token (PAT)	NjkxODMy...

[!TIP] To create a PAT in Jira Data Center, navigate to Profile > Personal Access Tokens and click Create token. Keep JIRA_EMAIL undefined (or do not set it) to trigger Bearer Token authentication.

Jira Cloud (Basic Auth)

Define these environment variables:

Environment Variable	Description	Example
JIRA_HOST	The root URL of your Jira Cloud instance	https://your-domain.atlassian.net
JIRA_EMAIL	The email associated with your Atlassian account	user@company.com
JIRA_API_TOKEN	Atlassian API Token	ATATT...

---

Local Setup & Development

1. Install Dependencies

npm install

2. Configure Environment

Create a .env file in the root directory for local testing:

Jira Data Center (PAT):

JIRA_HOST=https://jira.yourcompany.com
JIRA_API_TOKEN=your-personal-access-token
# Leave JIRA_EMAIL blank or omit it

Jira Cloud (Basic):

JIRA_HOST=https://your-domain.atlassian.net
JIRA_EMAIL=user@company.com
JIRA_API_TOKEN=your-api-token

3. Build the Server

Compiles the TypeScript source files into executable ESM JavaScript in the dist/ directory:

npm run build

---

Direct Execution (npx)

Once built or published, the server can be executed directly using Node.js:

# Run the local build
node bin/index.js

Or run via npx (if published or linked):

npx jira-mcp-server

---

Client Integration

To connect this MCP server to a client (e.g., Claude Desktop, Cursor, or Antigravity), use the following configuration layouts.

Claude Desktop Integration

Add the configuration snippet below to your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/jira-mcp/bin/index.js"
      ],
      "env": {
        "JIRA_HOST": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "user@company.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Cursor / Antigravity Integration

Configure a command-based MCP server in your IDE:

• Type: command
• Command: node /absolute/path/to/jira-mcp/bin/index.js
• Set the environment variables JIRA_HOST, JIRA_EMAIL, and JIRA_API_TOKEN in your system or project configuration.

---

Publishing to Corporate JFrog Artifactory

To distribute this package inside your organization using JFrog Artifactory as your private NPM registry:

1. Configure the Target Registry

Add a publishConfig object to your [package.json](file:///Users/yaakov.margalit/dev/jira-mcp/package.json) to redirect publishing to Artifactory:

"publishConfig": {
  "registry": "https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/"
}

Alternatively, create a .npmrc file in the root of the project:

registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/

2. Authenticate with JFrog Artifactory

Log in to your private registry using your corporate credentials:

npm login --registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/

3. Build & Publish

Compile the TypeScript code and upload the package:

npm run build
npm publish

4. Consume via npx

To run the server dynamically using npx from your private JFrog repository, specify the registry parameter:

npx --registry=https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/ jira-mcp-server

(Optional) If you set your global npm registry configuration to point to your Artifactory NPM proxy (which resolves both local and public NPM packages):

npm config set registry https://<your-jfrog-domain>/artifactory/api/npm/<npm-repository-name>/
npx jira-mcp-server