A
securityA
licenseA
qualityProvides integration with Jira's REST API, allowing AI assistants to manage Jira issues programmatically.
Last updated -
1
9
MIT License
Supports loading environment variables from a .env file for configuration, allowing easy setup of JIRA credentials and connection details.
Provides tools for interacting with JIRA APIs, enabling reading, creating, updating, and managing JIRA issues through standardized tools for querying, creating, updating, transitioning issues and adding comments.
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
Clone this repository:
git clone <repository-url> cd jira-mcpInstall dependencies:
npm installRun 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.netorhttps://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
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
File System Errors (EROFS)
The server automatically handles read-only file systems
Logs will fall back to stderr if file logging fails
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
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
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
Built with the Model Context Protocol TypeScript SDK.
Tools
Provides tools for AI assistants to interact with JIRA APIs, enabling them to read, create, update, and manage JIRA issues through standardized MCP tools.
Related MCP Servers
- -securityAlicense-qualityEnables 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.Last updated -6MIT License
- AsecurityAlicenseAqualityAn MCP server that enables communication with Jira, allowing users to perform operations like getting, searching, creating, and editing issues through natural language interaction.Last updated -120MIT License
- AsecurityAlicenseAqualityAn MCP server that enables AI assistants to interact with JIRA, allowing for querying issue details, creating and updating work items, and managing attachments through a standardized interface.Last updated -121MIT License