Servidor Jira MCP

Un servidor de Model Context Protocol (MCP) que proporciona herramientas para interactuar con Jira. Permite a Cursor y otros clientes MCP obtener tickets, gestionar tickets vinculados y actualizar el estado de los tickets.

Inicio rápido

1. Instalar dependencias

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

# Install project dependencies
uv sync

2. Configurar las credenciales de Jira

Recomendado: Token de acceso personal (PAT)

1. Inicia sesión en Jira: https://jira.telekom.de

2. Ve a tu perfil > Personal Access Tokens

3. Haz clic en "Create token"

4. Dale un nombre (p. ej., "Cursor MCP") y establece una fecha de caducidad

5. Importante: Asegúrate de que el token tenga permisos de "Read" o "Browse Projects"

6. Copia el token inmediatamente (no volverás a verlo)

Crea el archivo .env:

cp .env.example .env

Edita .env con tus credenciales:

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

Nota: Los tokens de API de Kantega SSO pueden tener restricciones de IP o requerir permisos configurados por el administrador. Los tokens de acceso personal son recomendados para la mayoría de los usuarios.

3. Configurar en Cursor

1. Abre Cursor

2. Ve a Settings > Tools and MCP

3. Añade esta configuración:

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

Importante: ¡Reemplaza la ruta y las credenciales con tus valores reales!

4. Reinicia Cursor por completo

4. Pruébalo

En el chat de Cursor, intenta:

• "Get details for Jira ticket PROJ-123"

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

• "Update PROJ-789 status to In Progress"

Características

Herramientas disponibles

Soporte de autenticación

• Bearer Token: Tokens de acceso personal (PAT) - Recomendado

• Basic Auth: Nombre de usuario + Token de API (Atlassian Cloud)

• Cookie Auth: Autenticación basada en sesión (opción de respaldo)

Detalles de las herramientas

get_ticket

Obtiene información completa del ticket.

Parámetros:

• ticket_id (cadena, requerido): ID o clave del ticket (p. ej., "PROJ-123")

Retorna:

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

Obtiene todos los tickets relacionados y subtareas.

Parámetros:

• ticket_id (cadena, requerido): ID o clave del ticket

Retorna:

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

Actualiza el estado del ticket con validación de flujo de trabajo.

Parámetros:

• ticket_id (cadena, requerido): ID o clave del ticket

• status (cadena, requerido): Estado objetivo (p. ej., "In Progress", "Done")

Retorna:

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

Nota: La herramienta valida las transiciones. Si no es válida, devuelve las transiciones disponibles.

Pruebas

Ejecutar pruebas

# 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

Pruebas manuales

Prueba el servidor directamente:

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

Presiona Ctrl+C para detener.

Solución de problemas

Errores de autenticación

Síntomas: "401 Unauthorized" o "403 Forbidden"

Soluciones:

• Lo más común: El token de acceso personal ha caducado; genera uno nuevo

• Verifica que tu PAT tenga permisos de "Read" o "Browse Projects"

• Comprueba que tu nombre de usuario coincida con el correo electrónico de tu cuenta de Jira

• Asegúrate de que JIRA_URL incluya https://

• Confirma JIRA_AUTH_TYPE=bearer para tokens de acceso personal

Ticket no encontrado

Síntomas: "404 Not Found"

Soluciones:

• Verifica que la clave del ticket sea correcta (p. ej., "PROJ-123")

• Comprueba que tienes permiso para ver el ticket

• Asegúrate de estar usando la instancia de Jira correcta

El servidor no aparece en Cursor

Soluciones:

• Verifica la ruta absoluta en tu configuración de MCP

• Comprueba que Python 3.12+ esté instalado: python3 --version

• Reinicia Cursor por completo (cierra y vuelve a abrir)

• Revisa la consola de desarrollador de Cursor en busca de errores

No se puede realizar la transición del ticket

Síntomas: "Invalid status transition"

Soluciones:

• El mensaje de error enumera las transiciones disponibles

• Los nombres de estado deben coincidir exactamente (sin distinguir entre mayúsculas y minúsculas)

• Comprueba tus permisos de flujo de trabajo de Jira

• Verifica que la transición sea válida para tu flujo de trabajo

Arquitectura

Este proyecto sigue los principios SOLID y una arquitectura limpia:

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

Principios clave:

• SOLID: Responsabilidad única, inversión de dependencia

• DRY: Sin duplicación, componentes reutilizables

• Seguridad de tipos: Sugerencias de tipo completas en todo el código

• Testeable: Separación clara de responsabilidades

Consulta ARCHITECTURE.md para obtener documentación técnica detallada.

Desarrollo

Estructura del proyecto

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

Añadir dependencias

uv add package-name

Ejecutar con una configuración diferente

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

Calidad del código

• Errores de linting: 0

• Cobertura de tipos: 100%

• Cobertura de pruebas: Pruebas de integración para las 3 herramientas

• Arquitectura: Cumple con SOLID + DRY

Requisitos

• Python 3.12+

• Cuenta de Jira con acceso a API

• Token de API de Jira (Kantega SSO Enterprise o Atlassian Cloud)

Licencia

Este proyecto se proporciona tal cual para su uso con Cursor y Jira.

Construido con las mejores prácticas siguiendo los principios SOLID y DRY 🚀