JIRA MCP Server

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:

Option 2: Install Globally

Install the package globally for repeated use:

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:

Or create a .env file:

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):

If installed globally:

From source:

Or run directly:

Example Tool Usage

Search Issues

Get Issue Details

Create New Issue

Update Issue

Add Comment

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

Testing

Set your environment variables and test the server:

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:

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.