Jira MCP Server

Ein Model Context Protocol (MCP) Server, der Tools für die Interaktion mit Jira bereitstellt. Ermöglicht es Cursor und anderen MCP-Clients, Tickets abzurufen, verknüpfte Tickets zu verwalten und den Ticketstatus zu aktualisieren.

Schnelleinstieg

1. Abhängigkeiten installieren

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

# Install project dependencies
uv sync

2. Jira-Anmeldedaten konfigurieren

Empfohlen: Personal Access Token (PAT)

1. Melden Sie sich bei Jira an: https://jira.telekom.de

2. Gehen Sie zu Ihrem Profil > Personal Access Tokens

3. Klicken Sie auf "Create token"

4. Geben Sie ihm einen Namen (z. B. "Cursor MCP") und legen Sie ein Ablaufdatum fest

5. Wichtig: Stellen Sie sicher, dass das Token über "Read"- oder "Browse Projects"-Berechtigungen verfügt

6. Kopieren Sie das Token sofort (Sie werden es nicht erneut sehen)

Erstellen Sie eine .env-Datei:

cp .env.example .env

Bearbeiten Sie die .env mit Ihren Anmeldedaten:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

Hinweis: Kantega SSO API-Token können IP-Beschränkungen haben oder vom Administrator konfigurierte Berechtigungen erfordern. Personal Access Tokens werden für die meisten Benutzer empfohlen.

3. In Cursor konfigurieren

1. Öffnen Sie Cursor

2. Gehen Sie zu Settings > Tools and MCP

3. Fügen Sie diese Konfiguration hinzu:

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

Wichtig: Ersetzen Sie den Pfad und die Anmeldedaten durch Ihre tatsächlichen Werte!

4. Starten Sie Cursor vollständig neu

4. Ausprobieren

Versuchen Sie im Cursor-Chat:

• "Get details for Jira ticket PROJ-123"

• "Show me all linked tickets for PROJ-456"

• "Update PROJ-789 status to In Progress"

Funktionen

Verfügbare Tools

Authentifizierungsunterstützung

• Bearer Token: Personal Access Tokens (PAT) - Empfohlen

• Basic Auth: Benutzername + API-Token (Atlassian Cloud)

• Cookie Auth: Sitzungsbasierte Authentifizierung (Fallback-Option)

Tool-Details

get_ticket

Ruft vollständige Ticketinformationen ab.

Parameter:

• ticket_id (string, erforderlich): Ticket-ID oder Schlüssel (z. B. "PROJ-123")

Rückgabe:

{
  "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

Ruft alle verknüpften Tickets und Unteraufgaben ab.

Parameter:

• ticket_id (string, erforderlich): Ticket-ID oder Schlüssel

Rückgabe:

{
  "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

Aktualisiert den Ticketstatus mit Workflow-Validierung.

Parameter:

• ticket_id (string, erforderlich): Ticket-ID oder Schlüssel

• status (string, erforderlich): Zielstatus (z. B. "In Progress", "Done")

Rückgabe:

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

Hinweis: Das Tool validiert Übergänge. Wenn diese ungültig sind, werden die verfügbaren Übergänge zurückgegeben.

Testen

Tests ausführen

# 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

Manuelles Testen

Testen Sie den Server direkt:

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

Drücken Sie Strg+C zum Beenden.

Fehlerbehebung

Authentifizierungsfehler

Symptome: "401 Unauthorized" oder "403 Forbidden"

Lösungen:

• Am häufigsten: Personal Access Token ist abgelaufen - generieren Sie ein neues

• Überprüfen Sie, ob Ihr PAT über "Read"- oder "Browse Projects"-Berechtigungen verfügt

• Stellen Sie sicher, dass Ihr Benutzername mit Ihrer Jira-Konto-E-Mail übereinstimmt

• Stellen Sie sicher, dass JIRA_URL https:// enthält

• Bestätigen Sie JIRA_AUTH_TYPE=bearer für Personal Access Tokens

Ticket nicht gefunden

Symptome: "404 Not Found"

Lösungen:

• Überprüfen Sie, ob der Ticketschlüssel korrekt ist (z. B. "PROJ-123")

• Prüfen Sie, ob Sie die Berechtigung haben, das Ticket anzuzeigen

• Stellen Sie sicher, dass Sie die richtige Jira-Instanz verwenden

Server erscheint nicht in Cursor

Lösungen:

• Überprüfen Sie den absoluten Pfad in Ihren MCP-Einstellungen

• Prüfen Sie, ob Python 3.12+ installiert ist: python3 --version

• Starten Sie Cursor vollständig neu (beenden und erneut öffnen)

• Überprüfen Sie die Entwicklerkonsole von Cursor auf Fehler

Ticket kann nicht überführt werden

Symptome: "Invalid status transition"

Lösungen:

• Die Fehlermeldung listet verfügbare Übergänge auf

• Statusnamen müssen exakt übereinstimmen (Groß-/Kleinschreibung wird ignoriert)

• Überprüfen Sie Ihre Jira-Workflow-Berechtigungen

• Überprüfen Sie, ob der Übergang für Ihren Workflow gültig ist

Architektur

Dieses Projekt folgt SOLID-Prinzipien und sauberer Architektur:

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

Kernprinzipien:

• SOLID: Single Responsibility, Dependency Inversion

• DRY: Keine Duplizierung, wiederverwendbare Komponenten

• Typsicherheit: Durchgehende Typ-Hinweise

• Testbar: Saubere Trennung der Zuständigkeiten

Siehe ARCHITECTURE.md für detaillierte technische Dokumentation.

Entwicklung

Projektstruktur

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

Abhängigkeiten hinzufügen

uv add package-name

Ausführen mit anderer Konfiguration

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

Codequalität

• Linting-Fehler: 0

• Typabdeckung: 100%

• Testabdeckung: Integrationstests für alle 3 Tools

• Architektur: SOLID + DRY konform

Anforderungen

• Python 3.12+

• Jira-Konto mit API-Zugriff

• Jira API-Token (Kantega SSO Enterprise oder Atlassian Cloud)

Lizenz

Dieses Projekt wird "wie besehen" für die Verwendung mit Cursor und Jira bereitgestellt.

Erstellt mit Best Practices gemäß SOLID- und DRY-Prinzipien 🚀