Skip to main content
Glama
hackdonalds

JIRA MCP Server

by hackdonalds
OverviewSchemaRelated ServersScoreDiscussions
JavaScript

JIRA MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with JIRA APIs. This server enables AI assistants to read, create, update, and manage JIRA issues through standardized MCP tools.

Features

This MCP server provides the following tools:

  • jira_get_issue: Get details of a specific JIRA issue by key

  • jira_search: Search issues using JQL (JIRA Query Language) with pagination support

  • jira_create_issue: Create a new issue with project, issue type, summary, and optional fields

  • jira_update_issue: Update an existing issue's fields (summary, description, assignee, priority)

  • jira_transition_issue: Transition an issue to a new status with optional comment

  • jira_add_comment: Add a comment to an existing issue

Related MCP server: Jira MCP Server

Requirements

  • Node.js 18.0 or higher

  • JIRA instance with API token access

  • Personal Access Token from your JIRA instance

Installation

Option 1: Quick Start with npx (Recommended)

Run the JIRA MCP server directly without installation:

npx @hackdonalds/jira-mcp

Option 2: Install Globally

Install the package globally for repeated use:

npm install -g @hackdonalds/jira-mcp
jira-mcp

Option 3: Install from Source

  1. Clone this repository:

    git clone <repository-url>
cd jira-mcp

  2. Install dependencies:

    npm install

  3. Run the server:

    npm start

Configuration

Set up your environment variables before running:

export JIRA_BASE_URL="https://your-jira-instance.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_EMAIL="your-email@company.com"  # Optional

Or create a .env file:

cp .env.example .env
# Edit .env with your JIRA credentials

Configuration

Environment Variables

The MCP server requires the following environment variables:

  • JIRA_BASE_URL: Your JIRA instance URL (without trailing slash)

    • Example: https://yourcompany.atlassian.net or https://jira.yourcompany.com

  • JIRA_API_TOKEN: Your JIRA Personal Access Token

Authentication

This server uses Bearer token authentication with Personal Access Tokens. The JIRA_EMAIL environment variable is optional and only used for logging purposes.

Supported JIRA versions:

  • Atlassian Cloud

  • JIRA Server 9.0+

  • JIRA Data Center

Usage

Starting the Server

Using npx (if not installed globally):

npx @hackdonalds/jira-mcp

If installed globally:

jira-mcp

From source:

npm start

Or run directly:

node server.js

Example Tool Usage

Search Issues

// Search for issues assigned to current user
{
  "tool": "jira_search",
  "arguments": {
    "jql": "assignee = currentUser() AND status != Done",
    "maxResults": 10
  }
}

Get Issue Details

{
  "tool": "jira_get_issue",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}

Create New Issue

{
  "tool": "jira_create_issue",
  "arguments": {
    "project": "PROJ",
    "issueType": "Task",
    "summary": "New task summary",
    "description": "Detailed description of the task",
    "priority": "High"
  }
}

Update Issue

{
  "tool": "jira_update_issue",
  "arguments": {
    "issueKey": "PROJ-123",
    "summary": "Updated summary",
    "assignee": "user-account-id"
  }
}

Add Comment

{
  "tool": "jira_add_comment",
  "arguments": {
    "issueKey": "PROJ-123",
    "comment": "This is a comment on the issue"
  }
}

Logging

The MCP server maintains comprehensive logging:

  • Log File: mcp.log (in current directory or system temp directory)

  • Log Levels: debug, info, warning, error

  • Fallback: If file logging fails, logs to stderr

  • Content: API requests, responses, errors, and tool executions

Error Handling

The server includes robust error handling:

  • Missing Configuration: Graceful degradation with helpful error messages

  • API Errors: Detailed logging of JIRA API response errors

  • Network Issues: Proper timeout and retry handling

  • File System: Automatic fallback for log file creation

Development

Project Structure

jira-mcp/
├── server.js          # Main MCP server implementation
├── package.json       # Node.js dependencies and scripts
├── .env.example       # Environment variable template
├── .gitignore         # Git ignore rules
├── README.md          # This file
└── mcp.log           # Log file (created at runtime)

Testing

Set your environment variables and test the server:

export JIRA_BASE_URL="https://your-jira-instance.com"
export JIRA_API_TOKEN="your-token-here"

# Test with npx
npx @hackdonalds/jira-mcp

# Or test from source
node server.js

API Compatibility

  • Uses JIRA REST API v2 (/rest/api/2/)

  • Compatible with both Atlassian Cloud and Server installations

  • Supports Bearer token authentication for modern JIRA instances

Troubleshooting

Common Issues

  1. Authentication Errors (401)

    • Verify your API token is correct and not expired

    • Check that your JIRA instance supports Bearer token authentication

    • Ensure JIRA_BASE_URL is correct and accessible

  2. File System Errors (EROFS)

    • The server automatically handles read-only file systems

    • Logs will fall back to stderr if file logging fails

  3. Empty Search Results

    • Verify your JQL syntax is correct

    • Check that you have permission to view the issues

    • Try a simpler query like project is not empty

  4. Network/Timeout Issues

    • Ensure your JIRA instance is accessible from your network

    • Check for corporate firewalls or VPN requirements

Debug Mode

Enable verbose logging by setting:

export NODE_ENV=development

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

Built with the Model Context Protocol TypeScript SDK.

Available Tools

6 tools
jira_add_commentAdd JIRA CommentC

Add a comment to a JIRA issue

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyYesThe JIRA issue key
commentYesComment text

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden but offers minimal behavioral insight. It states the action is 'Add' (implying a write/mutation), but doesn't disclose permission requirements, whether comments are editable/deletable, rate limits, or response format. For a mutation tool with zero annotation coverage, this leaves critical gaps.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, direct sentence with zero wasted words. It front-loads the core purpose efficiently, making it easy to parse. Every word earns its place without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with no annotations and no output schema, the description is insufficient. It doesn't explain what happens on success/failure, return values, error conditions, or side effects. Given the complexity of adding data to JIRA, more context is needed for safe and effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents both parameters (issueKey, comment) adequately. The description adds no additional meaning about parameter usage, constraints, or examples beyond what the schema provides, meeting the baseline for high coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Add') and target resource ('comment to a JIRA issue'), making the purpose immediately understandable. It distinguishes from siblings like jira_get_issue (read) and jira_update_issue (modify fields), though it doesn't explicitly differentiate from jira_create_issue which creates a different resource type.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing issue), when to choose this over jira_update_issue for communication, or any constraints. The agent must infer usage from the tool name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_create_issueCreate JIRA IssueC

Create a new JIRA issue

ParametersJSON Schema
NameRequiredDescriptionDefault
projectYesProject key
issueTypeYesIssue type (e.g., Bug, Task, Story)
summaryYesIssue summary
descriptionNoIssue description
assigneeNoAssignee account ID
priorityNoPriority name

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It states 'Create a new JIRA issue', which implies a write operation, but doesn't cover critical behaviors: whether it requires specific permissions, what happens on success/failure (e.g., returns an issue ID), if there are rate limits, or if it's idempotent. For a mutation tool with zero annotation coverage, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste: 'Create a new JIRA issue'. It's appropriately sized and front-loaded, directly stating the tool's purpose without unnecessary details. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the complexity (a mutation tool with 6 parameters) and lack of annotations and output schema, the description is incomplete. It doesn't explain return values (e.g., issue ID), error conditions, or behavioral nuances. For a creation tool with no structured output, the description should provide more context to be fully helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with all 6 parameters well-documented in the schema (e.g., 'Project key', 'Issue type'). The description adds no parameter information beyond what's in the schema. According to the rules, with high schema coverage (>80%), the baseline is 3 even with no param info in the description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Create a new JIRA issue' clearly states the verb ('Create') and resource ('JIRA issue'), which is adequate. However, it doesn't distinguish this tool from its sibling 'jira_update_issue' (which also modifies issues) or specify what makes creation unique versus updating. The purpose is clear but lacks sibling differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a project key), when not to use it (e.g., for existing issues), or refer to siblings like 'jira_update_issue' for modifications. Without any usage context, the agent must infer when this tool is appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_get_issueGet JIRA IssueC

Get details of a specific JIRA issue

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyYesThe JIRA issue key (e.g., PROJECT-123)

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states what the tool does ('Get details') without describing the return format, error handling, authentication needs, rate limits, or whether it's a read-only operation. For a tool with no annotations, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, clear sentence that is front-loaded with the core purpose. There is no wasted language or unnecessary elaboration, making it highly efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of annotations and output schema, the description is incomplete. It doesn't explain what details are returned, error conditions, or behavioral aspects like read-only nature. For a tool with no structured data beyond the input schema, the description should provide more context to be fully helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, with the parameter 'issueKey' fully documented in the schema. The description doesn't add any additional meaning beyond what the schema provides (e.g., it doesn't explain the format of issue keys beyond the schema's example). With high schema coverage, the baseline score of 3 is appropriate as the description doesn't compensate but also doesn't detract.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('Get details') and resource ('specific JIRA issue'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like 'jira_search' which might also retrieve issue information, missing the opportunity to specify this tool is for single-issue retrieval by key.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention that this is for retrieving a single issue by its key, as opposed to 'jira_search' for multiple issues or filtering, or when to prefer this over other read operations. No exclusions or prerequisites are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_transition_issueTransition JIRA IssueC

Transition an issue to a new status

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyYesThe JIRA issue key
transitionIdYesThe transition ID
commentNoOptional comment for the transition

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('transition') but doesn't cover critical aspects like required permissions, whether the transition is reversible, rate limits, or what happens to the issue's history. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero waste. It's front-loaded and appropriately sized for the tool's complexity, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation operation with 3 parameters), lack of annotations, and no output schema, the description is incomplete. It doesn't explain behavioral traits, usage context, or return values, leaving significant gaps for an agent to understand how to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all parameters (issueKey, transitionId, comment). The description adds no additional meaning beyond what the schema provides, such as explaining what a 'transitionId' represents or how to obtain it, meeting the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Transition an issue to a new status' clearly states the verb ('transition') and resource ('issue'), making the purpose understandable. However, it doesn't differentiate from sibling tools like 'jira_update_issue', which might also change issue states, so it lacks sibling distinction for a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing issue access), exclusions, or compare to siblings like 'jira_update_issue' for status changes, leaving usage unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

jira_update_issueUpdate JIRA IssueC

Update an existing JIRA issue

ParametersJSON Schema
NameRequiredDescriptionDefault
issueKeyYesThe JIRA issue key
summaryNoNew summary
descriptionNoNew description
assigneeNoNew assignee account ID
priorityNoNew priority name

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It states the tool updates issues but doesn't mention critical behaviors: whether it requires specific permissions, if updates are reversible, what happens to unspecified fields, or error handling. This leaves significant gaps for a mutation tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with zero wasted words. It's front-loaded with the core purpose and appropriately sized for what it conveys, making it easy to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a mutation tool with 5 parameters, no annotations, and no output schema, the description is inadequate. It doesn't explain what the tool returns, error conditions, or behavioral nuances like partial updates. Given the complexity and lack of structured data, more context is needed for effective use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so parameters are well-documented in the schema itself. The description doesn't add any semantic context beyond implying that parameters correspond to updatable fields, which is already clear from the schema. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Update an existing JIRA issue' clearly states the verb ('Update') and resource ('JIRA issue'), making the purpose immediately understandable. However, it doesn't differentiate from sibling tools like jira_transition_issue (which also modifies issues) or specify what aspects can be updated, keeping it from a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing an existing issue key), contrast with jira_create_issue for new issues or jira_transition_issue for status changes, or indicate any constraints like permission requirements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 6 tool updates
    • First observedjira_add_comment
    • First observedjira_create_issue
    • First observedjira_get_issue
    • First observedjira_search
    • First observedjira_transition_issue
    • First observedjira_update_issue
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific JIRA operations: creating, retrieving, updating, commenting on, searching for, and transitioning issues. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tools follow a consistent 'jira_verb_noun' pattern with snake_case throughout. The naming is predictable and uniform across all six tools.

Tool Count4/5

Six tools is reasonable for a JIRA server, covering core issue management operations. It's slightly lean but includes essential CRUD and workflow actions, with minor gaps like missing project or user management.

Completeness4/5

The toolset covers key JIRA workflows: create, read, update, search, comment, and transition issues. Minor gaps exist, such as no delete operation or project-level tools, but agents can handle most common tasks effectively.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • MCP JIRA Server

    Warzuponus
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI applications to manage JIRA issues, workflows, and tasks through a standardized MCP interface, facilitating real-time updates and seamless interaction with JIRA's API.
    9
    MIT

  • JIRA MCP Server

    scarnyc
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables natural language interaction with JIRA through MCP, providing 35 tools for issues, comments, transitions, projects, boards, sprints, epics, links, worklogs, versions, attachments, users, and fields.
    MIT

  • jira-helper

    namssy
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables natural language interaction with Jira Cloud tickets, including listing, searching, creating, and updating issues through a set of MCP tools.
    -

Appeared in Searches

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/hackdonalds/jira-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server