MCP Jira Integration

Una integración de Jira que permite a los LLMs actuar como gestores de proyectos y asistentes personales para equipos.

GitHub
10
Prueba este MCPPatrocinado

Documentación

Integración MCP Jira

Un servidor simple de Model Context Protocol (MCP) para Jira que permite a los LLMs actuar como gestores de proyectos y asistentes personales para equipos que usan Jira. Construido sobre la API REST de Jira v3.

Características

Herramientas MCP Principales

  • create_issue - Crear nuevos issues de Jira con formato adecuado y descripciones ADF
  • search_issues - Buscar issues usando JQL con formato inteligente y paginación
  • get_sprint_status - Obtener informes completos de progreso de sprints con métricas
  • get_team_workload - Analizar cargas de trabajo y capacidad de los miembros del equipo
  • generate_standup_report - Generar informes diarios de standup automáticamente

Capacidades de Gestión de Proyectos

  • Soporte Multi-Proyecto: Trabajar con múltiples proyectos especificando claves de proyecto dinámicamente
  • Seguimiento del progreso de sprints con indicadores visuales
  • Análisis de carga de trabajo del equipo y planificación de capacidad
  • Generación automatizada de informes diarios de standup
  • Creación de issues con priorización adecuada
  • Búsqueda inteligente y filtrado de issues

Fiabilidad

  • Reintento automático con retroceso exponencial en límites de tasa (429) y errores transitorios (503)
  • Paginación para conjuntos de resultados grandes
  • Manejo de fechas consciente de la zona horaria
  • Manejo elegante de estados e tipos de issues personalizados de Jira

Requisitos

  • Python 3.8 o superior
  • Cuenta de Jira Cloud con token de API
  • Cliente compatible con MCP (como Claude Desktop)

Configuración Rápida

  1. Clonar e instalar:
git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
  1. Configurar credenciales de Jira:
cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your.email@domain.com
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123
  1. Probar el servidor:
.venv/bin/python -m mcp_jira

Deberías ver Initializing MCP Jira server... en la salida. Presiona Ctrl+C para detener.

Ejemplos de Uso

Creación de Issues

"Crea un bug de alta prioridad para el sistema de inicio de sesión que no funciona correctamente"

  • Asigna automáticamente el tipo de issue, prioridad y formato adecuados

Gestión de Sprints

"¿Cuál es el estado actual de nuestro sprint?"

  • Obtiene un informe completo de progreso con métricas e indicadores visuales

Gestión de Equipos

"Muéstrame la carga de trabajo del equipo para john.doe, jane.smith, mike.wilson"

  • Analiza la capacidad y proporciona la distribución de la carga de trabajo

Standups Diarios

"Genera el informe de standup de hoy"

  • Crea un informe formateado con elementos completados, en progreso y bloqueados

Integración MCP

Con Claude Desktop

El archivo de configuración se encuentra en:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Añade la siguiente entrada, reemplazando /path/to/mcp-jira con la ruta absoluta donde clonaste el repositorio:

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

Nota: Usa el binario de Python desde dentro de la carpeta .venv — esto asegura que todas las dependencias estén disponibles. El campo cwd no es necesario; el servidor resuelve su configuración usando rutas absolutas internamente.

Para encontrar la ruta correcta, ejecuta esto desde dentro del directorio del proyecto:

echo "$(pwd)/.venv/bin/python"

Reinicia Claude Desktop después de guardar la configuración.

Con Otros Clientes MCP

El servidor sigue el protocolo MCP estándar y funciona con cualquier cliente compatible con MCP.

Configuración

Variables de Entorno Requeridas

  • JIRA_URL - La URL de tu instancia de Jira
  • JIRA_USERNAME - Tu nombre de usuario/correo de Jira
  • JIRA_API_TOKEN - Tu token de API de Jira
  • PROJECT_KEY - Clave de proyecto predeterminada para operaciones (se puede sobrescribir por solicitud)

Configuraciones Opcionales

  • DEFAULT_BOARD_ID - Tablero predeterminado para operaciones de sprint (se puede sobrescribir por solicitud)
  • STORY_POINTS_FIELD - ID de campo personalizado para Story Points (predeterminado: customfield_10026)
  • DEBUG_MODE - Habilitar registro de depuración (predeterminado: false)
  • LOG_LEVEL - Nivel de registro (predeterminado: INFO)

Obtención del Token de API de Jira

  1. Ve a Configuración de la Cuenta Atlassian
  2. Haz clic en "Crear token de API"
  3. Dale un nombre y copia el token
  4. Usa tu correo como nombre de usuario y el token como contraseña

Arquitectura

Esta implementación prioriza la simplicidad y la fiabilidad:

  • Archivo único de servidor MCP - Todas las herramientas en un solo lugar
  • Protocolo MCP estándar - Usa el SDK oficial de MCP
  • API REST de Jira v3 - Usa el Formato de Documento Atlassian (ADF) para descripciones
  • Formato enriquecido - Proporciona informes hermosos y legibles
  • Reintento con retroceso - Maneja límites de tasa y errores transitorios de la API de Jira automáticamente
  • Paginación - Obtiene todos los resultados para conjuntos de issues grandes
  • Manejo de errores - Manejo elegante de problemas de la API de Jira y estados personalizados
  • Soporte asíncrono - Operaciones rápidas y receptivas

Solución de Problemas

Problemas Comunes

  1. "No se encontró sprint activo"

    • Asegúrate de que tu tablero tenga un sprint activo
    • Verifica que DEFAULT_BOARD_ID esté configurado correctamente

  2. Errores de autenticación

    • Verifica que tu token de API sea correcto
    • Comprueba que tu nombre de usuario sea tu dirección de correo

  3. Errores de permisos

    • Asegúrate de que tu usuario de Jira tenga los permisos de proyecto adecuados
    • Verifica que la clave del proyecto exista y tengas acceso

Modo de Depuración

Configura DEBUG_MODE=true en tu archivo .env para un registro detallado.

Desarrollo

  1. Haz un fork del repositorio
  2. Configura un entorno de desarrollo:
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
  1. Ejecuta las pruebas:
python -m pytest tests/ -v
  1. Envía una solicitud de extracción

Licencia

Licencia MIT - consulta el archivo LICENSE