Skip to main content
Glama
tarangbhavsar

MCP JIRA Server

by tarangbhavsar
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

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

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tarangbhavsar/mcp-jira-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server