Jira MCP Server

A Model Context Protocol (MCP) server that provides comprehensive integration with Jira. This server enables AI assistants to interact with Jira through a standardized interface, allowing them to search, create, update, and manage Jira issues programmatically.

Features

This MCP server provides the following tools for Jira integration:

• 🔍 Search Issues - Search for issues using JQL (Jira Query Language)

• 📄 Get Issue Details - Retrieve detailed information about specific issues

• ➕ Create Issues - Create new issues in any project

• ✏️ Update Issues - Modify existing issue fields

• 💬 Add Comments - Add comments to issues

• 🔄 Get Transitions - View available status transitions

• ⚡ Transition Issues - Change issue status/workflow state

• 👤 Assign Issues - Assign issues to users

• 📋 List Projects - Get all accessible projects

• 🔎 Search Users - Find users by name or email

• 📝 Get Comments - Retrieve all comments from an issue

• 📊 Get Boards - List all accessible Scrum and Kanban boards

• 📈 Get Board Issues - Retrieve issues from a specific board

Prerequisites

Before you begin, ensure you have:

• Node.js 18 or higher installed

• A Jira account (Cloud or Data Center)

• Jira API credentials (email and API token)

• Claude Desktop or another MCP-compatible client

Installation

1. Clone or Download

Or if you're starting from scratch in this directory, the files are already created.

2. Install Dependencies

This will install:

• @modelcontextprotocol/sdk - MCP SDK for building servers

• axios - HTTP client for Jira API calls

• dotenv - Environment variable management

• TypeScript and Node.js type definitions

3. Build the Project

This compiles the TypeScript code to JavaScript in the build/ directory.

Configuration

Step 1: Get Your Jira API Token

1. Log in to your Jira account at https://your-domain.atlassian.net

2. Go to Account Settings → Security → API tokens

3. Click Create API token

4. Give it a label (e.g., "MCP Server") and click Create

5. Copy the token immediately (you won't be able to see it again)

Step 2: Create Environment File

Create a .env file in the root directory:

Important Notes:

• JIRA_HOST should be just the domain without https://

• Use the email associated with your Jira account

• Keep your API token secure and never commit it to version control

Step 3: Configure Claude Desktop

Add the server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Replace /ABSOLUTE/PATH/TO/jira-mcp with the actual absolute path to your project directory.

Step 4: Restart Claude Desktop

Completely quit and restart Claude Desktop for the changes to take effect.

Usage

Once configured, you can ask Claude to interact with Jira using natural language. Here are some examples:

Example Queries

Search for Issues

Behind the scenes, Claude will use JQL like:

• project = PROJ AND type = Bug AND status = Open

• assignee = currentUser() AND status = "In Progress"

• created >= -1w AND priority = High

Get Issue Details

Create New Issues

Update Issues

Add Comments

Transition Issues

For transitions, Claude will first get available transitions using jira_get_transitions, then execute the appropriate one.

Assign Issues

You'll need the user's account ID, which Claude can find using jira_search_users.

List Projects

Search Users

Get Boards

Get Board Issues

Available Tools Reference

jira_search_issues

Search for issues using JQL.

Parameters:

• jql (required): JQL query string

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

• startAt (optional): Starting index (default: 0)

Example:

jira_get_issue

Get detailed information about an issue.

Parameters:

• issueKey (required): Issue key (e.g., "PROJ-123")

Example:

jira_create_issue

Create a new issue.

Parameters:

• projectKey (required): Project key

• summary (required): Issue summary

• issueType (required): Issue type (Bug, Task, Story, etc.)

• description (optional): Issue description

• priority (optional): Priority (High, Medium, Low, etc.)

Example:

jira_update_issue

Update an existing issue.

Parameters:

• issueKey (required): Issue key

• summary (optional): Updated summary

• description (optional): Updated description

• priority (optional): Updated priority

Example:

jira_add_comment

Add a comment to an issue.

Parameters:

• issueKey (required): Issue key

• comment (required): Comment text

Example:

jira_get_transitions

Get available transitions for an issue.

Parameters:

• issueKey (required): Issue key

Example:

jira_transition_issue

Transition an issue to a new status.

Parameters:

• issueKey (required): Issue key

• transitionId (required): Transition ID (from get_transitions)

Example:

jira_assign_issue

Assign an issue to a user.

Parameters:

• issueKey (required): Issue key

• accountId (required): User account ID (use null to unassign)

Example:

jira_get_projects

Get all accessible projects. No parameters required.

jira_search_users

Search for users.

Parameters:

• query (required): Search query (name or email)

Example:

jira_get_comments

Get all comments from an issue.

Parameters:

• issueKey (required): Issue key

Example:

jira_get_boards

Get a list of all accessible Jira boards (Scrum and Kanban).

Parameters:

• startAt (optional): Starting index (default: 0)

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

Example:

jira_get_board_issues

Get issues from a specific Jira board. Useful for retrieving stories, tasks, and bugs from a board.

Parameters:

• boardId (required): Board ID number

• startAt (optional): Starting index (default: 0)

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

• jql (optional): JQL filter to apply to board issues

Example:

Development

Project Structure

Available Scripts

• npm run build - Compile TypeScript to JavaScript

• npm run watch - Watch mode for development

• npm run dev - Run with Node.js debugger

Making Changes

1. Edit TypeScript files in src/

2. Run npm run build to compile

3. Restart Claude Desktop to test changes

Troubleshooting

Server Not Appearing in Claude

1. Check that the path in claude_desktop_config.json is absolute and correct

2. Verify the build/index.js file exists (run npm run build)

3. Completely quit and restart Claude Desktop (not just close the window)

4. Check Claude Desktop logs for errors

Authentication Errors

• Verify your JIRA_HOST doesn't include https://

• Confirm your API token is valid and hasn't expired

• Ensure the email matches your Jira account

• Check that your account has permission to access the Jira instance

API Errors

• Check that project keys and issue keys are correct (case-sensitive)

• Verify you have permission to perform the operation

• Some operations may require specific Jira permissions

• Review the error message returned by the tool

JQL Query Issues

• Test your JQL in Jira's search interface first

• Ensure field names are correct and quoted if they contain spaces

• Use proper JQL operators (=, !=, IN, NOT IN, etc.)

• Common fields: project, status, assignee, priority, type, created, updated

Security Notes

• Never commit your .env file or API tokens

• API tokens have the same permissions as your user account

• Consider creating a dedicated service account for automation

• Regularly rotate your API tokens

• Use environment variables for all sensitive data

JQL Reference

Common JQL examples:

API Rate Limits

Jira Cloud has rate limits:

• 10 requests per second per user

• Consider implementing delays for bulk operations

• The server handles individual requests; batch operations may hit limits

License

MIT

Support

For issues and questions:

• Check the troubleshooting section above

• Review Jira API documentation: https://developer.atlassian.com/cloud/jira/platform/rest/v3/

• Review MCP documentation: https://modelcontextprotocol.io

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Submit a pull request

Note: This is an unofficial tool and is not affiliated with or endorsed by Atlassian.