MCP JIRA Server

# 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: ```bash # 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):** ```bash 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):** ```bash 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 ```bash # Install Kerberos dependencies brew install krb5 # Install Python Kerberos packages pip install requests-gssapi ``` #### Linux (Ubuntu/Debian) ```bash # Install Kerberos dependencies sudo apt-get install libkrb5-dev krb5-user # Install Python Kerberos packages pip install requests-gssapi ``` #### Initialize Kerberos Ticket ```bash # 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: ```bash cp .env.example .env ``` Edit `.env` with your JIRA configuration: ```bash # 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: ```bash # 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`: ```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 ```python { "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 ```python { "tool": "jira_search_issues", "arguments": { "jql": "project = PROJ AND status = 'In Progress'", "max_results": 50 } } ``` ### Transition Issue ```python { "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: ```python # 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:** ```bash # 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:** ```bash # 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 ```bash # 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 ```bash # 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: ```mermaid 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