Jira Mcp Server

Jira MCP Server

[](https://github.com/stolostron/jira-mcp-server/actions/workflows/ci.yml)

A Model Context Protocol (MCP) server that provides seamless integration with Jira instances. This server enables AI applications to interact with Jira issues, projects, and workflows through a standardized interface.

Jira Cloud Migration

The server has been updated to work with the new Jira Cloud instance. To migrate:

1. Pull the latest changes

cd /path/to/jira-mcp-server && git pull

1. Update your .env file

JIRA_SERVER_URL=https://redhat.atlassian.net
JIRA_ACCESS_TOKEN=
JIRA_EMAIL=@redhat.com

1. Get your API token — Go to https://id.atlassian.com/manage-profile/security/api-tokens and click "Create API token"

1. Reconnect — In Claude Code run /mcp to reconnect, or restart your client (Cursor, Gemini CLI, etc.)

All custom field IDs and work type IDs have been updated in the code. No other changes needed.

Table of Contents

1. [Features](#features)
2. [Installation](#installation)
3. [Configuration](#configuration)
4. [Usage](#usage)
5. [Client Configuration](#client-configuration)
6. [Available Tools](#available-tools)
7. [Slash Commands](#slash-commands)
8. [Automatic Update Notifications](#automatic-update-notifications)
9. [Development](#development)
10. [Troubleshooting](#troubleshooting)
11. [Advanced Configuration](#advanced-configuration)
12. [License & Contributing](#license--contributing)

Features

• Issue Management: Search, create, update, and transition Jira issues
• Team Management: Define teams with multiple members and assign them to issues as watchers
• Component Aliases: Use short, memorable aliases instead of long component names
• Watcher Management: Add, remove, and list watchers on issues
• Issue Linking: Create links between issues with different relationship types (blocks, relates to, etc.)
• Project Access: List and browse Jira projects and components
• User Search: Find Jira users by name, email, or username for assignment
• Comments: Add comments to issues with security levels
• Time Logging: Log work time on issues with detailed comments
• Workflow Enforcement: Requires fix_version before transitioning beyond "In Progress"
• JQL Support: Full Jira Query Language support for advanced searching
• Rate Limiting: Built-in throttling to respect Jira API limits
• Async Operations: Fully asynchronous for optimal performance
• Type Safety: Pydantic models for structured data validation
• Multiple Transports: Support for both STDIO and SSE (HTTP) transports
• Client Integration: Works with Claude Code, Gemini CLI, Cursor, and other MCP clients

Installation

1. Clone the repository:

git clone https://github.com/stolostron/jira-mcp-server.git
cd jira-mcp-server

1. Install the package:

pip install -e .

Or install with development dependencies:

pip install -e ".[dev]"

> macOS: Use pip3 instead of pip: > ``bash > pip3 install -e . > ``

Configuration

1. Copy the example environment file:

cp .env.example .env

1. Edit .env with your Jira credentials:

JIRA_SERVER_URL=https://your-company.atlassian.net
JIRA_ACCESS_TOKEN=your-personal-access-token
JIRA_EMAIL=your-email@company.com
JIRA_VERIFY_SSL=true
JIRA_TIMEOUT=30
JIRA_MAX_RESULTS=100

# Optional: Configure teams (JSON format with usernames, NOT email addresses)
JIRA_TEAMS={"frontend": ["alice", "bob"], "backend": ["charlie", "david"], "devops": ["eve"]}

# Optional: Configure component aliases (JSON format mapping aliases to actual component names)
JIRA_COMPONENT_ALIASES={"ui": "User Interface", "be": "Backend Services", "infra": "Infrastructure"}

Note: Team member names must be Jira usernames, not email addresses.

Jira Cloud Setup

For Jira Cloud (Atlassian Cloud), you'll need to:

1. Create a personal access token:

• Go to https://id.atlassian.com/manage-profile/security/api-tokens
• Click "Create API token"
• Use the access token as the JIRA_ACCESS_TOKEN

1. Set JIRA_EMAIL to the email address associated with your Atlassian account (required for Cloud authentication)

1. Use your full Atlassian domain (e.g., https://yourcompany.atlassian.net)

Jira Server/Data Center Setup

For on-premise Jira instances:

1. Use your Jira server URL
2. Use your personal access token
3. Ensure the user has appropriate permissions for the operations you need

Usage

Running the Server

STDIO Transport (Default)

Start the MCP server with STDIO transport (for use with MCP clients):

jira-mcp-server

Or run directly with Python:

python -m jira_mcp_server.main

SSE Transport (HTTP)

Start the MCP server with SSE (Server-Sent Events) transport for HTTP-based communication:

jira-mcp-server --transport sse

Or with custom host and port:

jira-mcp-server --transport sse --host 0.0.0.0 --port 9000

Or run directly with Python:

python -m jira_mcp_server.main --transport sse --host 127.0.0.1 --port 8000

When running with SSE transport, the server will expose:

• SSE Endpoint: http://127.0.0.1:8000/sse (for real-time server-to-client communication)
• Message Endpoint: http://127.0.0.1:8000/messages/ (for client-to-server communication)

Transport Types

• STDIO: Best for integration with MCP clients like Claude Code, IDEs, or command-line tools
• SSE: Best for web applications, REST API integration, or when you need HTTP-based communication

SSE Client Example

An example SSE client is provided to demonstrate how to connect to the server using HTTP transport:

# First, start the server with SSE transport
jira-mcp-server --transport sse

# Then run the example client (in another terminal)
python examples/sse_client.py

The example client demonstrates:

• Connecting to the SSE endpoint
• Listing available tools
• Getting Jira projects
• Searching for issues

Client Configuration

Claude Code

Claude Code is Anthropic's code editor application that supports MCP servers for enhanced AI-powered development assistance.

Configuration File Locations

Claude Code looks for MCP server configurations in the following locations (in order of precedence):

• Project-specific: .mcp.json in your project directory
• Project-specific: .claude/settings.json in your project directory
• Global: ~/.mcp.json in your home directory
• Global: ~/.claude/settings.json in your home directory

Recommended: Use a project-specific .mcp.json or .claude/settings.json file for better portability and team sharing.

Setup Steps

1. Create a project-specific configuration file (recommended, same format in all options):

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "python",
      "args": ["-m", "jira_mcp_server.main"],
      "cwd": "/home/user/workspace_git/jira-mcp-server",
    }
  }
}

> macOS: Use python3 (or the full path /usr/local/bin/python3) instead of python: > ``json > { > "mcpServers": { > "jira-mcp-server": { > "command": "/usr/local/bin/python3", > "args": ["-m", "jira_mcp_server.main"], > "cwd": "/home/user/workspace_git/jira-mcp-server" > } > } > } > ``

Option A: Create .mcp.json in your project root:

Option B: Create .claude/settings.json in your project root:

1. Or create a global configuration:

Option A: For global access across all projects, create ~/.mcp.json:

Option B: Or create ~/.claude/settings.json:

1. Restart Claude Code to apply the configuration.

1. Verify the connection by asking Claude to list your Jira issues or projects.

Example Usage

Once connected, you can ask Claude:

• "Show me all my assigned Jira issues"
• "Create a new bug report for the login issue"
• "What are the high priority issues in the PROJECT project?"
• "Add a comment to issue PROJ-123 saying it's been fixed"
• "Log 2 hours of work on issue PROJ-123 for debugging the login bug"
• "Link issue PROJ-123 to PROJ-456 with a 'blocks' relationship"
• "Show me all available link types for this Jira instance"
• "Assign the frontend team to issue PROJ-123"
• "Create a new issue and assign it to the backend team"
• "Who is watching issue PROJ-123?"
• "Add alice as a watcher to issue PROJ-456"
• "Find all issues assigned to the frontend team"
• "Show me open issues assigned to the backend team"

Gemini CLI

Gemini CLI is Google's command-line interface that supports MCP servers.

Configuration File Locations

• Global: ~/.gemini/settings.json
• Project-specific: /.gemini/settings.json

Setup Steps

1. Create or edit the configuration file:

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "python",
      "args": ["-m", "jira_mcp_server.main"],
      "cwd": "/home/user/workspace_git/jira-mcp-server",
      "timeout": 30000,
      "trust": false
    }
  }
}

> macOS: Use python3 (or the full path /usr/local/bin/python3) instead of python for the "command" value.

1. Restart Gemini CLI to apply the configuration.

1. Test the connection by running a command that interacts with Jira.

Example Usage

# Ask about Jira issues
gemini "Show me my assigned Jira issues"

# Create a new issue
gemini "Create a new bug report titled 'Login Error' in project PROJ"

# Log time on an issue
gemini "Log 2 hours on issue PROJ-123 for implementing the new feature"

# Link two issues together
gemini "Link issue PROJ-123 to PROJ-456 with a blocks relationship"

Cursor

Cursor is a code editor that supports MCP servers for AI-powered development assistance.

Recommended model: GPT-5 or claude-4-sonnet-1m (MAX)

Configuration File Locations

• Project-specific: /.cursor/mcp.json
• Global: ~/.cursor/mcp.json

Setup Steps

1. Create or edit the configuration file:

{
  "mcpServers": {
    "jira-mcp-server": {
      "command": "python",
      "args": ["-m", "jira_mcp_server.main"],
      "cwd": "/home/user/workspace_git/jira-mcp-server",
    }
  }
}

> macOS: Use python3 (or the full path /usr/local/bin/python3) instead of python for the "command" value.

1. Restart Cursor to apply the configuration.

1. Use the integration by asking Cursor to help with Jira-related tasks in your code.

Available Tools

The server provides the following MCP tools:

search_issues

Search for issues using JQL (Jira Query Language):

# Example JQL queries:
"project = MYPROJ AND status = Open"
"assignee = currentUser() AND priority = High"
"created >= -7d AND project in (PROJ1, PROJ2)"

search_issues_by_team

Search for issues assigned to any member of a team:

search_issues_by_team(
    team_name="frontend",
    project_key="PROJ",  # Optional
    status="In Progress"  # Optional
)

This automatically generates a JQL query like:

project = PROJ AND (assignee = "alice" OR assignee = "bob") AND status = "In Progress"

get_issue

Get detailed information about a specific issue:

get_issue(issue_key="PROJ-123")

create_issue

Create a new issue:

create_issue(
    project_key="PROJ",
    summary="Fix login bug",
    description="Users cannot log in with special characters",
    issue_type="Bug",
    priority="High"
)

update_issue

Update an existing issue:

update_issue(
    issue_key="PROJ-123",
    summary="Updated summary",
    assignee="john.doe"
)

transition_issue

Change the status of an issue:

transition_issue(
    issue_key="PROJ-123",
    transition="Done"
)

Note: Transitions beyond "New", "Backlog", and "In Progress" require fix_version to be set on the issue. This ensures all completed work is tied to a release version.

add_comment

Add a comment to an issue:

add_comment(
    issue_key="PROJ-123",
    comment="This has been resolved"
)

link_issue

Create a link between two issues:

link_issue(
    link_type="Blocks",
    inward_issue="PROJ-123",
    outward_issue="PROJ-456",
    comment="This issue blocks the other one"
)

get_link_types

Get all available issue link types:

get_link_types()

log_time

Log time spent on an issue:

log_time(
    issue_key="PROJ-123",
    time_spent="2h 30m",
    comment="Implemented new feature"
)

get_projects

List all accessible projects:

get_projects()

get_project_components

Get components for a specific project:

get_project_components(project_key="PROJ")

search_users

Search for Jira users by name, email, or username:

search_users(
    query="john",
    max_results=50
)

Returns matching users with their accountid, name, displayname, email_address, and active status. Useful for finding user IDs when assigning issues.

debug_issue_fields

Get all raw Jira fields for an issue (useful for debugging custom fields):

debug_issue_fields(issue_key="PROJ-123")

Team Management Tools

list_teams

List all configured teams and their members:

list_teams()

add_team

Add or update a team configuration:

add_team(
    team_name="frontend",
    members=["alice", "bob", "charlie"]
)

remove_team

Remove a team configuration:

remove_team(team_name="frontend")

assign_team_to_issue

Assign a team to an issue by adding all team members as watchers:

assign_team_to_issue(
    issue_key="PROJ-123",
    team_name="frontend"
)

Note: When creating issues, you can also use the team parameter to automatically add team members as watchers:

create_issue(
    project_key="PROJ",
    summary="Fix login bug",
    description="Users cannot log in",
    issue_type="Bug",
    priority="High",
    team="frontend"  # All frontend team members will be added as watchers
)

Watcher Management Tools

get_issue_watchers

Get all watchers for an issue:

get_issue_watchers(issue_key="PROJ-123")

add_watcher_to_issue

Add a single watcher to an issue:

add_watcher_to_issue(
    issue_key="PROJ-123",
    username="alice"
)

remove_watcher_from_issue

Remove a watcher from an issue:

remove_watcher_from_issue(
    issue_key="PROJ-123",
    username="alice"
)

Component Alias Management Tools

list_component_aliases

List all configured component aliases:

list_component_aliases()

add_component_alias

Add or update a component alias:

add_component_alias(
    alias="ui",
    component_name="User Interface"
)

remove_component_alias

Remove a component alias:

remove_component_alias(alias="ui")

Available Resources

The server also provides MCP resources for read-only access:

• jira://issue/{issue_key} - Get formatted issue details
• jira://projects - Get formatted list of all projects

Slash Commands

The project includes custom slash commands that can be installed for use in Claude Code.

/jira-create — Interactive Issue Creation

The /jira-create command provides a guided, interactive flow for creating Jira issues. It walks you through each step using prompts:

1. Issue Type — Select from Story, Bug, Task, Spike, Feature, Epic, or Sub-task
2. Specialist Agent — A specialist agent (e.g., story-specialist, bug-specialist) is launched to help craft the summary and description based on the issue type
3. Core Fields — Priority, Work Type, Original Estimate, Story Points
4. Categorization — Component, Labels, Target Version
5. Parent / Linking — Link to a parent issue or related issues
6. Confirmation — Review all fields before creation
7. **P

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: stolostron
• Source: stolostron/jira-mcp-server
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.