Jira MCP Server

A Model Context Protocol (MCP) server that integrates with Atlassian Jira to search issues, retrieve details, access comments, create new issues, and update issues.

Features

• 🔍 Search Issues: Use JQL (Jira Query Language) to find issues

• 📋 Get Issue Details: Retrieve complete issue information including acceptance criteria

• 💬 Access Comments: Get all comments for any issue

• ➕ Create Issues: Create new issues with custom fields, labels, and assignments

• ✏️ Update Issues: Change status, assignee, summary, description, and priority

• 🔄 Status Transitions: View available status transitions and change issue status

• 🔧 Configurable: Works with any Jira Cloud instance

Related MCP server: JIRA MCP Tools

Installation

# Clone the repository
git clone https://github.com/fajarmf/jira-mcp.git
cd jira-mcp

# Install dependencies
npm install

# Build the project
npm run build

Configuration

Environment Variables

Set the following environment variables:

export JIRA_BASE_URL="https://your-domain.atlassian.net"
export JIRA_EMAIL="your-email@example.com"
export JIRA_API_TOKEN="your-api-token"

Getting a Jira API Token

1. Go to Atlassian Account Settings

2. Click "Create API token"

3. Give it a label and copy the token

4. Use this token as your JIRA_API_TOKEN

MCP Configuration

Add the server to your MCP configuration file (~/.mcp.json):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token"
      }
    }
  }
}

Usage

Once configured, the following tools are available:

jira_get_issue

Get detailed information about a specific Jira issue.

Parameters:

• issueKey (required): The Jira issue key (e.g., "PROJECT-123")

Example:

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

jira_search_issues

Search for issues using JQL (Jira Query Language).

Parameters:

• jql (required): JQL query string

• maxResults (optional): Maximum number of results (default: 50)

Example:

{
  "tool": "jira_search_issues",
  "arguments": {
    "jql": "project = PROJECT AND status = \"In Progress\"",
    "maxResults": 10
  }
}

jira_get_issue_comments

Get all comments for a specific issue.

Parameters:

• issueKey (required): The Jira issue key (e.g., "PROJECT-123")

Example:

{
  "tool": "jira_get_issue_comments",
  "arguments": {
    "issueKey": "PROJECT-123"
  }
}

jira_get_transitions

Get available status transitions for a specific issue.

Parameters:

• issueKey (required): The Jira issue key (e.g., "PROJECT-123")

Example:

{
  "tool": "jira_get_transitions",
  "arguments": {
    "issueKey": "PROJECT-123"
  }
}

jira_create_issue

Create a new Jira issue.

Parameters:

• projectKey (required): The project key where the issue will be created (e.g., "PROJ")

• summary (required): Issue summary/title

• description (optional): Issue description

• issueType (optional): Issue type (e.g., "Bug", "Story", "Task") - defaults to "Task"

• priority (optional): Priority name (e.g., "High", "Medium", "Low")

• assignee (optional): Assignee email address or account ID

• labels (optional): Array of labels to add to the issue

Example - Basic issue:

{
  "tool": "jira_create_issue",
  "arguments": {
    "projectKey": "PROJ",
    "summary": "Fix login bug",
    "description": "Users cannot login when using special characters in password",
    "issueType": "Bug",
    "priority": "High"
  }
}

Example - Full featured issue:

{
  "tool": "jira_create_issue",
  "arguments": {
    "projectKey": "PROJ",
    "summary": "Implement user dashboard",
    "description": "Create a comprehensive user dashboard with analytics and quick actions",
    "issueType": "Story",
    "priority": "Medium",
    "assignee": "developer@example.com",
    "labels": ["frontend", "dashboard", "user-experience"]
  }
}

jira_update_issue

Update a Jira issue's status, assignee, summary, description, or priority.

Parameters:

• issueKey (required): The Jira issue key (e.g., "PROJECT-123")

• transition (optional): Status transition name or ID

• assignee (optional): Assignee email address or account ID

• summary (optional): Updated issue summary

• description (optional): Updated issue description

• priority (optional): Priority name (e.g., "High", "Medium", "Low")

Example - Change status:

{
  "tool": "jira_update_issue",
  "arguments": {
    "issueKey": "PROJECT-123",
    "transition": "In Review"
  }
}

Example - Update multiple fields:

{
  "tool": "jira_update_issue",
  "arguments": {
    "issueKey": "PROJECT-123",
    "transition": "Done",
    "assignee": "developer@example.com",
    "priority": "Low"
  }
}

JQL Examples

Here are some useful JQL queries you can use with the search tool:

# Find open issues assigned to you
assignee = currentUser() AND resolution = Unresolved

# Find high priority bugs
priority = High AND type = Bug

# Find recently updated issues
updated >= -7d

# Find issues in specific status
status in ("To Do", "In Progress")

# Find issues by project and component
project = MYPROJECT AND component = "Backend"

# Find overdue issues
due < now() AND resolution = Unresolved

Features

Acceptance Criteria Extraction

The server automatically extracts acceptance criteria from issue descriptions using common patterns:

• "Acceptance Criteria:" sections

• "AC:" sections

• Given/When/Then scenarios

• Checkbox lists

• Bullet points

Error Handling

• Comprehensive error handling for API failures

• Clear error messages for authentication issues

• Graceful handling of missing issues or invalid queries

Development

Project Structure

jira-mcp/
├── src/
│   └── index.ts        # Main MCP server implementation
├── build/              # Compiled JavaScript files
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Running

npm start

Requirements

• Node.js 16+

• TypeScript 5.0+

• Valid Jira Cloud instance with API access

• Jira API token with appropriate permissions

Permissions Required

Your Jira API token needs the following permissions:

• Read access to projects and issues

• Read access to comments

• Browse projects permission

• Create issues permission (for creating new issues)

• Write access to issues (for updating status, assignee, etc.)

• Transition issues permission

Troubleshooting

Authentication Errors

• Verify your email and API token are correct

• Check that your API token has the necessary permissions

• Ensure your Jira base URL is correct (should not include /rest/api/3)

Connection Issues

• Verify the Jira base URL format: https://your-domain.atlassian.net

• Check your internet connection

• Ensure Jira Cloud is accessible from your network

JQL Errors

• Validate your JQL syntax in Jira's issue navigator first

• Check that field names and values exist in your Jira instance

• Remember JQL is case-sensitive for some operators

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues or questions:

• Create an issue on GitHub

• Check Jira's REST API documentation

• Review the MCP protocol documentation