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