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

git clone <repository-url>
cd jira-mcp

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

2. Install Dependencies

npm install

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

npm run build

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:

JIRA_HOST=your-domain.atlassian.net
JIRA_EMAIL=your-email@example.com
JIRA_API_TOKEN=your-api-token-here

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

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/jira-mcp/build/index.js"],
      "env": {
        "JIRA_HOST": "your-domain.atlassian.net",
        "JIRA_EMAIL": "your-email@example.com",
        "JIRA_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

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

"Find all open bugs in the PROJ project"
"Show me issues assigned to me that are in progress"
"Search for issues created this week with high priority"

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

"Show me the details of issue PROJ-123"
"What's the status of PROJ-456?"

Create New Issues

"Create a new bug in project PROJ with summary 'Login page not loading' and description 'Users cannot access the login page'"
"Create a task in PROJ called 'Update documentation' with high priority"

Update Issues

"Update PROJ-123 to change the summary to 'Fix login page loading issue'"
"Change the priority of PROJ-456 to High"

Add Comments

"Add a comment to PROJ-123 saying 'This has been fixed in the latest release'"
"Comment on PROJ-456: 'Waiting for QA team to verify'"

Transition Issues

"Move PROJ-123 to In Progress"
"Close PROJ-456"

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

Assign Issues

"Assign PROJ-123 to john.doe@example.com"
"Unassign PROJ-456"

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

List Projects

"What Jira projects do I have access to?"
"Show me all available projects"

Search Users

"Find user john.doe"
"Search for users named Smith"

Get Boards

"Show me all available boards"
"List all Scrum boards"
"What boards do I have access to?"

Get Board Issues

"Show me all issues from board 123"
"Get all stories from the development board"
"List issues from board 456 that are in progress"

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:

{
  "jql": "project = PROJ AND status = Open",
  "maxResults": 10
}

jira_get_issue

Get detailed information about an issue.

Parameters:

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

Example:

{
  "issueKey": "PROJ-123"
}

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:

{
  "projectKey": "PROJ",
  "summary": "Fix login bug",
  "issueType": "Bug",
  "description": "Login page not loading",
  "priority": "High"
}

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:

{
  "issueKey": "PROJ-123",
  "summary": "Updated summary",
  "priority": "High"
}

jira_add_comment

Add a comment to an issue.

Parameters:

• issueKey (required): Issue key
• comment (required): Comment text

Example:

{
  "issueKey": "PROJ-123",
  "comment": "This has been fixed"
}

jira_get_transitions

Get available transitions for an issue.

Parameters:

• issueKey (required): Issue key

Example:

{
  "issueKey": "PROJ-123"
}

jira_transition_issue

Transition an issue to a new status.

Parameters:

• issueKey (required): Issue key
• transitionId (required): Transition ID (from get_transitions)

Example:

{
  "issueKey": "PROJ-123",
  "transitionId": "31"
}

jira_assign_issue

Assign an issue to a user.

Parameters:

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

Example:

{
  "issueKey": "PROJ-123",
  "accountId": "5d123456789abc0def123456"
}

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:

{
  "query": "john.doe"
}

jira_get_comments

Get all comments from an issue.

Parameters:

• issueKey (required): Issue key

Example:

{
  "issueKey": "PROJ-123"
}

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:

{
  "startAt": 0,
  "maxResults": 50
}

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:

{
  "boardId": 123,
  "jql": "type = Story AND status = 'In Progress'",
  "maxResults": 20
}

Development

Project Structure

jira-mcp/
 src/
    index.ts          # Main MCP server implementation
    jira-client.ts    # Jira API client wrapper
 build/                # Compiled JavaScript (generated)
 package.json          # Project dependencies
 tsconfig.json         # TypeScript configuration
 .env                  # Environment variables (create this)
 .gitignore           # Git ignore rules
 README.md            # This file

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:

# Issues in a project
project = PROJ

# Open bugs
project = PROJ AND type = Bug AND status = Open

# Assigned to me
assignee = currentUser()

# High priority issues
priority = High

# Created recently
created >= -7d

# Multiple conditions
project = PROJ AND status IN (Open, "In Progress") AND assignee = currentUser()

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.