Herramientas JIRA MCP

Un protocolo de contexto de modelo (MCP) para interactuar con las API de JIRA a través de Claude Desktop.

Características

• Buscar problemas de JIRA usando JQL (lenguaje de consulta de JIRA)
• Listar proyectos de JIRA para el usuario autenticado
• Crear, actualizar y eliminar problemas de JIRA
• Agregar comentarios y problemas de transición entre estados
• Búsqueda de usuarios (con soporte de cumplimiento del RGPD)

Instalación

1. Clonar este repositorio:
   git clone https://github.com/yourusername/mcp-jira.git cd mcp-jira
2. Crear y activar un entorno virtual:
   # On macOS/Linux python -m venv venv source venv/bin/activate # On Windows python -m venv venv .\venv\Scripts\activate
3. Instalar dependencias:
   pip install -r requirements.txt
4. Cree un archivo .env en la raíz del proyecto:
   touch .env
5. Agregue sus credenciales de JIRA al archivo .env :
   JIRA_SERVER=https://your-domain.atlassian.net JIRA_EMAIL=your.email@example.com JIRA_API_TOKEN=your_api_token_here
6. Pruebe la instalación:
   # Run all tests python -m pytest # Run a specific test file python -m pytest tests/test_search_issues.py
7. Inicie el servidor MCP:
   python run.py

Configuración del entorno

Token de API de JIRA

Necesitará un token de API de JIRA para autenticarse con su instancia de JIRA:

1. Inicie sesión en su cuenta de Atlassian
2. Vaya a Configuración de la cuenta > Seguridad > Crear y administrar tokens API
3. Haga clic en "Crear token de API".
4. Asígnele un nombre (por ejemplo, "Integración de escritorio de Claude")
5. Haga clic en "Crear" y guarde de forma segura el token generado.

Cumplimiento del RGPD

Si está utilizando una instancia de JIRA Cloud (que probablemente esté en modo estricto GDPR):

1. Las búsquedas de usuarios solo coincidirán con nombres para mostrar y direcciones de correo electrónico.
2. No se admiten búsquedas basadas en nombre de usuario
3. Los resultados pueden estar limitados según los permisos del usuario.
4. La herramienta gestiona automáticamente los requisitos del RGPD, pero es posible que tengas que ajustar tus patrones de búsqueda.

Solución de problemas

Problemas comunes y soluciones:

1. ModuleNotFoundError: No hay ningún módulo llamado 'src'
   # Run with PYTHONPATH set PYTHONPATH=/path/to/mcp-jira python run.py
2. Error de autenticación de la API de JIRA
   • Verifique que su token API sea correcto
   • Comprueba que tu correo electrónico coincida con tu cuenta de Atlassian
   • Asegúrese de que la URL de su instancia de JIRA sea correcta e incluya "https://"
3. Errores relacionados con el RGPD
   • Si ve errores de "parámetro de nombre de usuario no compatible", su instancia está en modo GDPR
   • Utilice nombres para mostrar o direcciones de correo electrónico para realizar búsquedas en lugar de nombres de usuario
   • La herramienta ajustará automáticamente las llamadas API para el cumplimiento del RGPD

Obtener un token de API de JIRA

1. Inicie sesión en su cuenta de Atlassian
2. Vaya a Configuración de la cuenta > Seguridad > Crear y administrar tokens API
3. Haga clic en "Crear token de API".
4. Asígnele un nombre (por ejemplo, "Integración de escritorio de Claude")
5. Haga clic en "Crear" y guarde de forma segura el token generado.

Herramientas

Problemas de búsqueda

Busque problemas de JIRA utilizando JQL (lenguaje de consulta JIRA).

Parámetros:

• jql: cadena del lenguaje de consulta JIRA (p. ej., "proyecto=DEMO AND estado=Abierto")
• max_results: Número máximo de resultados a devolver (predeterminado: 10)
• campos: Lista separada por comas de campos que se incluirán en los resultados (predeterminado: "resumen, estado, asignado, prioridad, tipo de problema")

Crear problema

Crear un nuevo problema de JIRA en un proyecto específico.

Parámetros:

• project_key: La clave del proyecto para crear el problema (por ejemplo, "DEMO")
• Resumen: Resumen del problema
• Descripción: Descripción del problema (opcional)
• issue_type: Tipo de problema (predeterminado: "Tarea", puede ser "Error", "Historia", etc.)
• prioridad: Prioridad del problema (opcional, p. ej., "Alta", "Media", "Baja")
• cesionario: Nombre de usuario al que asignar el problema (opcional)

Problema de actualización

Actualizar un problema de JIRA existente con nuevos valores.

Parámetros:

• issue_key: La clave del problema de JIRA (por ejemplo, "PROJ-123")
• Resumen: Nuevo resumen del problema (opcional)
• Descripción: Nueva descripción del problema (opcional)
• Estado: Nuevo estado del problema (opcional, por ejemplo, "En progreso", "Listo")
• Prioridad: Nueva prioridad para el problema (opcional, por ejemplo, "Alta", "Media", "Baja")
• cesionario: Nuevo cesionario para la emisión (opcional)
• Comentario: Comentario para agregar al problema (opcional)

Eliminar problema

Eliminar un problema de JIRA (requiere confirmación explícita).

Parámetros:

• issue_key: La clave del problema de JIRA (por ejemplo, "PROJ-123")
• confirmar: Bandera de confirmación para evitar la eliminación accidental, debe establecerse en Verdadero

Lista de proyectos

Enumera los proyectos de JIRA para el usuario autenticado.

Parámetros:

• límite: Número máximo de proyectos a devolver (predeterminado: 10)

Añadir comentario

Agregar un comentario a un problema de JIRA existente.

Parámetros:

• issue_key: La clave del problema de JIRA (por ejemplo, "PROJ-123")
• Comentario: El texto del comentario que se agregará al problema.

Problema de transición

Transición de un problema de JIRA a un nuevo estado.

Parámetros:

• issue_key: La clave del problema de JIRA (por ejemplo, "PROJ-123")
• Estado: el estado al que se desea transferir el problema (por ejemplo, "En progreso", "Listo")
• comentario: Comentario opcional para agregar con la transición

Obtener detalles del problema

Obtenga información detallada sobre un problema de JIRA.

Parámetros:

• issue_key: La clave del problema de JIRA (por ejemplo, "PROJ-123")
• include_comments: si se deben incluir comentarios sobre el problema en la respuesta (valor predeterminado: Falso)

Buscar usuarios

Busca usuarios de JIRA por nombre, correo electrónico o nombre de usuario. Esta herramienta te ayuda a encontrarlos cuando necesitas asignar incidencias o añadir observadores.

Nota importante : En las instancias de JIRA Cloud con el modo estricto del RGPD habilitado (predeterminado para las instancias más recientes), la búsqueda de usuarios debe usar el parámetro query en lugar del username . La herramienta gestiona esto automáticamente, pero es posible que deba ajustar sus patrones de búsqueda según corresponda.

Parámetros:

• query (str): La cadena de búsqueda que se debe comparar con los nombres para mostrar y las direcciones de correo electrónico del usuario
  • Para instancias que cumplen con el RGPD, esto busca nombres para mostrar y direcciones de correo electrónico.
  • La búsqueda no distingue entre mayúsculas y minúsculas y coincide con cadenas parciales.
  • Ejemplo: "john" coincidirá con "John Doe" y " johnny@example.com ".
• max_results (int, opcional): Número máximo de usuarios a devolver (valor predeterminado: 10)
• include_active_users (bool, opcional): incluye usuarios activos en los resultados de búsqueda (valor predeterminado: verdadero)
• include_inactive_users (bool, opcional): incluir usuarios inactivos en los resultados de búsqueda (valor predeterminado: falso)

Ejemplo de uso:

Notas sobre el cumplimiento del RGPD:

• En el modo estricto del RGPD, la búsqueda de usuarios es más restrictiva para proteger su privacidad.
• La búsqueda coincide únicamente con los nombres de usuario y las direcciones de correo electrónico.
• No se admite la coincidencia exacta de nombre de usuario
• La búsqueda siempre no distingue entre mayúsculas y minúsculas.
• Se admiten coincidencias parciales (por ejemplo, "jo" coincidirá con "John")
• Los resultados pueden estar limitados según los permisos y la configuración de privacidad del usuario.

Ejemplo de uso

Desarrollo

Para los desarrolladores que quieran modificar o ampliar este MCP:

1. Clonar el repositorio
2. Configurar un entorno virtual: python -m venv venv && source venv/bin/activate
3. Instalar dependencias: pip install -r requirements.txt
4. Ejecutar pruebas: python -m pytest
5. Realiza tus cambios
6. Prueba con Claude Desktop