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

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="[email protected]"  # 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
  • For Atlassian Cloud: Create at id.atlassian.com/manage-profile/security/api-tokens
  • For Server/Data Center: Create in your JIRA profile settings

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.