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.

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

• Node.js 18.0 or higher
• JIRA instance with API token access
• Personal Access Token from your JIRA instance

Run the JIRA MCP server directly without installation:

npx @hackdonalds/jira-mcp

Install the package globally for repeated use:

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

1. Clone this repository:

   git clone <repository-url>
   cd jira-mcp

2. Install dependencies:

   npm install

3. Run the server:

   npm start

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

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

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

npx @hackdonalds/jira-mcp

jira-mcp

npm start

Or run directly:

node server.js

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

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

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

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

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

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

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

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)

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

• Uses JIRA REST API v2 (/rest/api/2/)
• Compatible with both Atlassian Cloud and Server installations
• Supports Bearer token authentication for modern JIRA instances

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

Enable verbose logging by setting:

export NODE_ENV=development

MIT License - see LICENSE file for details.

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.