Which integrations are available for this server?

Provides comprehensive access to JIRA's API with tools for managing issues, searching with JQL, handling comments and attachments, executing workflow transitions, and managing projects. Supports custom fields with automatic resolution and type conversion, and offers multiple authentication methods including Kerberos, API tokens, and basic auth.

How do I use MCP JIRA Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP JIRA Server search for open bugs in project ABC assigned to me" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

MCP JIRA Server

A comprehensive Model Context Protocol (MCP) server for JIRA built with FastMCP that provides full API access with Kerberos authentication and extensive custom fields support.

Features

⚡ FastMCP Framework: Built with FastMCP 2.0 for simplified, decorator-based server implementation
🔐 Kerberos/GSSAPI Authentication: Native support for enterprise Kerberos authentication
🎫 Multiple Auth Methods: Kerberos, API Token, and Basic Authentication
🔧 Custom Fields: Automatic field resolution and type conversion
📝 Complete Operations: Issues, Search, Comments, Attachments, Transitions, Projects
🔄 Retry Logic: Automatic retry with backoff for failed requests
💾 Field Caching: Efficient custom field metadata caching

Installation

Prerequisites

Python 3.10 or higher
Access to a JIRA instance
For Kerberos: Valid Kerberos ticket or keytab file

Install UV (Recommended)

If you don't have uv installed, install it first:

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Create Virtual Environment and Install Dependencies

Using uv (recommended - fast and efficient):

cd /Users/hanuman/.gemini/antigravity/scratch/mcp-jira-server

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install dependencies
uv pip install -e .

Using pip (alternative):

cd /Users/hanuman/.gemini/antigravity/scratch/mcp-jira-server

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Install dependencies
pip install -e .

Note: This project uses FastMCP 2.0, which provides a streamlined decorator-based approach to building MCP servers. Using uv is recommended for faster dependency resolution and installation.

Kerberos Setup

macOS

# Install Kerberos dependencies
brew install krb5

# Install Python Kerberos packages
pip install requests-gssapi

Linux (Ubuntu/Debian)

# Install Kerberos dependencies
sudo apt-get install libkrb5-dev krb5-user

# Install Python Kerberos packages
pip install requests-gssapi

Initialize Kerberos Ticket

# Using kinit (interactive)
kinit your.username@REALM

# Verify ticket
klist

# Or use keytab file (set in .env)
kinit -kt /path/to/your.keytab principal@REALM

Configuration

Create a .env file in the project root:

cp .env.example .env

Edit .env with your JIRA configuration:

# JIRA Configuration
JIRA_URL=https://jira.yourcompany.com

# Authentication Method
AUTH_METHOD=kerberos  # or api_token or basic

# Kerberos (when AUTH_METHOD=kerberos)
KERBEROS_PRINCIPAL=HTTP/jira.yourcompany.com@REALM
KERBEROS_KEYTAB_PATH=/path/to/your.keytab
KERBEROS_MUTUAL_AUTH=true

# API Token (when AUTH_METHOD=api_token)
JIRA_EMAIL=your.email@example.com
JIRA_API_TOKEN=your_api_token_here

# Optional Settings
LOG_LEVEL=INFO
CUSTOM_FIELDS_CACHE_TTL=3600
REQUEST_TIMEOUT=30

Usage

Running the Server

Make sure your virtual environment is activated first:

# Activate virtual environment if not already active
source .venv/bin/activate  # macOS/Linux
# or
.venv\Scripts\activate  # Windows

# Run as module
python -m mcp_jira

# Or use entry point (after installation)
mcp-jira-server

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jira": {
      "command": "python",
      "args": ["-m", "mcp_jira"],
      "env": {
        "JIRA_URL": "https://jira.yourcompany.com",
        "AUTH_METHOD": "kerberos"
      }
    }
  }
}

Other MCP Clients

The server uses stdio transport and can be integrated with any MCP client that supports stdio.

Available Tools

Issue Operations

jira_create_issue: Create new issue with custom fields
jira_get_issue: Get issue details
jira_update_issue: Update issue fields
jira_delete_issue: Delete issue
jira_assign_issue: Assign issue to user

Search & Query

jira_search_issues: Search using JQL with pagination

Comments

jira_add_comment: Add comment to issue

Attachments

jira_upload_attachment: Upload file to issue

Workflow

jira_get_transitions: Get available transitions
jira_transition_issue: Move issue through workflow

Metadata

jira_list_projects: List accessible projects
jira_get_custom_fields: Get custom field definitions

Available Resources

jira://projects: List of all projects
jira://custom-fields: Custom field definitions
jira://current-user: Current user information

Examples

Create Issue with Custom Fields

{
  "tool": "jira_create_issue",
  "arguments": {
    "project": "PROJ",
    "summary": "Example issue",
    "issue_type": "Bug",
    "description": "This is a test issue",
    "priority": "High",
    "custom_fields": {
      "Story Points": 5,
      "Sprint": "Sprint 23",
      "Custom Date Field": "2024-12-31"
    }
  }
}

Search Issues

{
  "tool": "jira_search_issues",
  "arguments": {
    "jql": "project = PROJ AND status = 'In Progress'",
    "max_results": 50
  }
}

Transition Issue

{
  "tool": "jira_transition_issue",
  "arguments": {
    "issue_key": "PROJ-123",
    "transition": "In Progress",
    "comment": "Starting work on this issue"
  }
}

Custom Fields

The server automatically resolves custom field names to IDs and handles type conversion:

Text fields: Single/multi-line text
Select fields: Single/multi-select options
Date fields: Date and DateTime
User fields: User picker
Number fields: Numeric values
Arrays: Multi-value fields

Custom Field Usage

You can reference custom fields by name or ID:

# By name
"custom_fields": {
  "Story Points": 5,
  "Epic Link": "PROJ-100"
}

# By ID
"custom_fields": {
  "customfield_10016": 5,
  "customfield_10014": "PROJ-100"
}

Troubleshooting

Kerberos Issues

Problem: No valid Kerberos ticket found

Solution:

# Initialize ticket
kinit your.username@REALM

# Verify
klist

Problem: Server not found in Kerberos database

Solution: Verify KERBEROS_PRINCIPAL matches your JIRA server's SPN

Connection Issues

Problem: Failed to connect to JIRA

Solution:

Verify JIRA_URL is correct
Check network connectivity
Verify authentication credentials
Check logs for detailed error messages

Custom Fields Not Found

Problem: Custom field not resolved

Solution:

# List all custom fields
# Use jira_get_custom_fields tool to see available fields

# Clear cache if fields were recently added
# Restart the server

Development

Running Tests

# Install dev dependencies with uv
uv pip install -e ".[dev]"

# Or with pip
pip install -e ".[dev]"

# Run tests
pytest tests/

# Run with coverage
pytest --cov=mcp_jira tests/

Code Quality

# Format code
black src/

# Type checking
mypy src/

# Linting
ruff check src/

Architecture

The server uses FastMCP for a streamlined, decorator-based implementation with a layered architecture:

graph TB
    subgraph "MCP Clients"
        CD[Claude Desktop]
        OC[Other MCP Clients]
    end

    subgraph "MCP JIRA Server"
        subgraph "Server Layer"
            MCP[FastMCP Server<br/>mcp_server.py]
            TOOLS["@mcp.tool() Decorators"]
            RES["@mcp.resource() Decorators"]
        end

        subgraph "Operations Layer"
            ISS[Issues<br/>issues.py]
            SRCH[Search<br/>search.py]
            CMT[Comments<br/>comments.py]
            ATT[Attachments<br/>attachments.py]
            TRN[Transitions<br/>transitions.py]
            PRJ[Projects<br/>projects.py]
        end

        subgraph "Client Layer"
            JC[JIRA Client<br/>jira_client.py]
            CF[Custom Fields Manager<br/>custom_fields.py]
        end

        subgraph "Authentication Layer"
            AM[Auth Manager<br/>auth_manager.py]
            KRB[Kerberos Auth<br/>kerberos_auth.py]
            ADFS[ADFS Auth<br/>adfs_auth.py]
            API[API Token /<br/>Basic Auth]
        end

        subgraph "Configuration"
            CFG[Config<br/>config.py]
            ENV[.env File]
        end

        subgraph "Models"
            MDL[Pydantic Types<br/>types.py]
        end
    end

    subgraph "External Services"
        JIRA[(JIRA Server<br/>REST API)]
        KDC[Kerberos KDC]
        ADFSS[ADFS Server]
    end

    CD <-->|stdio| MCP
    OC <-->|stdio| MCP
    
    MCP --> TOOLS
    MCP --> RES
    TOOLS --> ISS
    TOOLS --> SRCH
    TOOLS --> CMT
    TOOLS --> ATT
    TOOLS --> TRN
    TOOLS --> PRJ
    RES --> PRJ
    
    ISS --> JC
    SRCH --> JC
    CMT --> JC
    ATT --> JC
    TRN --> JC
    PRJ --> JC
    
    JC --> CF
    JC --> AM
    
    AM --> KRB
    AM --> ADFS
    AM --> API
    
    KRB --> KDC
    ADFS --> ADFSS
    JC --> JIRA
    
    CFG --> ENV
    MCP --> CFG
    JC --> CFG

    classDef serverLayer fill:#4a90d9,stroke:#2c5aa0,color:#fff
    classDef opsLayer fill:#50b356,stroke:#2d7a32,color:#fff
    classDef clientLayer fill:#f5a623,stroke:#c78515,color:#fff
    classDef authLayer fill:#9b59b6,stroke:#6c3483,color:#fff
    classDef external fill:#e74c3c,stroke:#a93226,color:#fff
    classDef config fill:#95a5a6,stroke:#717d7e,color:#fff

    class MCP,TOOLS,RES serverLayer
    class ISS,SRCH,CMT,ATT,TRN,PRJ opsLayer
    class JC,CF clientLayer
    class AM,KRB,ADFS,API authLayer
    class JIRA,KDC,ADFSS external
    class CFG,ENV,MDL config

Component Overview

Layer	Components	Responsibility
Server	`mcp_server.py`	FastMCP server with `@mcp.tool()` and `@mcp.resource()` decorators
Operations	`issues.py`, `search.py`, `comments.py`, `attachments.py`, `transitions.py`, `projects.py`	JIRA API operations and business logic
Client	`jira_client.py`, `custom_fields.py`	HTTP client, retry logic, and custom field resolution
Authentication	`auth_manager.py`, `kerberos_auth.py`, `adfs_auth.py`	Multi-method auth (Kerberos, ADFS, API Token, Basic)
Models	`types.py`	Pydantic type definitions for request/response validation
Config	`config.py`	Environment-based configuration management

Directory Structure

mcp-jira-server/
├── src/mcp_jira/
│   ├── auth/              # Authentication (Kerberos, ADFS, API token, basic)
│   ├── client/            # JIRA client and custom fields manager
│   ├── models/            # Pydantic type definitions
│   ├── operations/        # JIRA operations (issues, search, etc.)
│   ├── server/
│   │   └── mcp_server.py  # FastMCP server with @mcp.tool and @mcp.resource decorators
│   ├── config.py          # Configuration management
│   └── __main__.py        # Entry point
├── tests/                 # Test suite
├── pyproject.toml         # Project metadata
└── .env.example           # Example configuration

Key Design Principles

Layered Architecture: Clear separation between server, operations, client, and auth layers
Decorator-Based Tools: Simple @mcp.tool() and @mcp.resource() decorators for MCP integration
Pluggable Authentication: Support for multiple auth methods via AuthManager abstraction
Automatic Type Conversion: Parameter validation and type conversion from function signatures
Custom Field Resolution: Automatic field name-to-ID mapping with caching

License

MIT License

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

Check the troubleshooting section
Review JIRA API documentation
Check MCP protocol documentation

MCP JIRA Server

Features

Installation

Prerequisites

Install UV (Recommended)

Create Virtual Environment and Install Dependencies

Kerberos Setup

macOS

Linux (Ubuntu/Debian)

Initialize Kerberos Ticket

Configuration

Usage

Running the Server

MCP Client Configuration

Claude Desktop

Other MCP Clients

Available Tools

Issue Operations

Search & Query

Comments

Attachments

Workflow

Metadata

Available Resources

Examples

Create Issue with Custom Fields

Search Issues

Transition Issue

Custom Fields

Custom Field Usage

Troubleshooting

Kerberos Issues

Connection Issues

Custom Fields Not Found

Development

Running Tests

Code Quality

Architecture

Component Overview

Directory Structure

Key Design Principles

License

Contributing

Support

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API