Jira MCP Server

Jira MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Jira. Enables Cursor and other MCP clients to fetch tickets, manage linked tickets, and update ticket status.

Quick Start

1. Install Dependencies

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Configure Jira Credentials

Recommended: Personal Access Token (PAT)

1. Log into Jira: https://jira.telekom.de
2. Go to your profile > Personal Access Tokens
3. Click "Create token"
4. Give it a name (e.g., "Cursor MCP") and set expiration
5. Important: Ensure the token has "Read" or "Browse Projects" permissions
6. Copy the token immediately (you won't see it again)

Create .env file:

cp .env.example .env

Edit .env with your credentials:

JIRA_URL=https://jira.telekom.de
[email protected]
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

Note: Kantega SSO API tokens may have IP restrictions or require admin-configured permissions. Personal Access Tokens are recommended for most users.

3. Configure in Cursor

1. Open Cursor
2. Go to Settings > Tools and MCP
3. Add this configuration:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

Important: Replace the path and credentials with your actual values!

4. Restart Cursor completely

4. Try It Out

In Cursor chat, try:

• "Get details for Jira ticket PROJ-123"
• "Show me all linked tickets for PROJ-456"
• "Update PROJ-789 status to In Progress"

Features

Available Tools

Authentication Support

• Bearer Token: Personal Access Tokens (PAT) - Recommended
• Basic Auth: Username + API token (Atlassian Cloud)
• Cookie Auth: Session-based authentication (fallback option)

Tool Details

get_ticket

Fetches complete ticket information.

Parameters:

• ticket_id (string, required): Ticket ID or key (e.g., "PROJ-123")

Returns:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

Fetches all related tickets and subtasks.

Parameters:

• ticket_id (string, required): Ticket ID or key

Returns:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

Updates ticket status with workflow validation.

Parameters:

• ticket_id (string, required): Ticket ID or key
• status (string, required): Target status (e.g., "In Progress", "Done")

Returns:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

Note: The tool validates transitions. If invalid, it returns available transitions.

Testing

Run Tests

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

Manual Testing

Test the server directly:

uv run --env-file .env -m src

Press Ctrl+C to stop.

Troubleshooting

Authentication Errors

Symptoms: "401 Unauthorized" or "403 Forbidden"

Solutions:

• Most common: Personal Access Token is expired - generate a new one
• Verify your PAT has "Read" or "Browse Projects" permissions
• Check your username matches your Jira account email
• Ensure JIRA_URL includes https://
• Confirm JIRA_AUTH_TYPE=bearer for Personal Access Tokens

Ticket Not Found

Symptoms: "404 Not Found"

Solutions:

• Verify the ticket key is correct (e.g., "PROJ-123")
• Check you have permission to view the ticket
• Ensure you're using the correct Jira instance

Server Not Appearing in Cursor

Solutions:

• Verify the absolute path in your MCP settings
• Check Python 3.12+ is installed: python3 --version
• Restart Cursor completely (quit and reopen)
• Check Cursor's developer console for errors

Cannot Transition Ticket

Symptoms: "Invalid status transition"

Solutions:

• The error message lists available transitions
• Status names must match exactly (case-insensitive)
• Check your Jira workflow permissions
• Verify the transition is valid for your workflow

Architecture

This project follows SOLID principles and clean architecture:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

Key Principles:

• SOLID: Single responsibility, dependency inversion
• DRY: No duplication, reusable components
• Type Safety: Full type hints throughout
• Testable: Clean separation of concerns

See ARCHITECTURE.md for detailed technical documentation.

Development

Project Structure

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

Adding Dependencies

uv add package-name

Running with Different Config

uv run --env-file .env.production -m src

Code Quality

• Linting errors: 0
• Type coverage: 100%
• Test coverage: Integration tests for all 3 tools
• Architecture: SOLID + DRY compliant

Requirements

• Python 3.12+
• Jira account with API access
• Jira API token (Kantega SSO Enterprise or Atlassian Cloud)

License

This project is provided as-is for use with Cursor and Jira.

Built with best practices following SOLID and DRY principles 🚀