Integración de MCP con Jira

Un servidor sencillo del Protocolo de Contexto de Modelo (MCP) para Jira que permite a los LLM actuar como gestores de proyectos y asistentes personales para equipos que utilizan Jira. Construido sobre la API REST de Jira v3.

Características

Herramientas principales de MCP

• create_issue - Crea nuevas incidencias en Jira con el formato adecuado y descripciones en ADF

• search_issues - Busca incidencias usando JQL con formato inteligente y paginación

• get_sprint_status - Obtiene informes completos del progreso del sprint con métricas

• get_team_workload - Analiza la carga de trabajo y la capacidad de los miembros del equipo

• generate_standup_report - Genera informes diarios de standup automáticamente

Capacidades de gestión de proyectos

• Soporte para múltiples proyectos: Trabaja con varios proyectos especificando las claves de proyecto de forma dinámica

• Seguimiento del progreso del sprint con indicadores visuales

• Análisis de la carga de trabajo del equipo y planificación de la capacidad

• Generación automatizada de informes diarios de standup

• Creación de incidencias con la priorización adecuada

• Búsqueda y filtrado inteligente de incidencias

Fiabilidad

• Reintento automático con retroceso exponencial ante límites de tasa (429) y errores transitorios (503)

• Paginación para grandes conjuntos de resultados

• Gestión de fechas con reconocimiento de zona horaria

• Gestión elegante de estados personalizados de Jira y tipos de incidencia

Related MCP server: JIRA MCP Server

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 .

2. Configurar las 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

3. Probar el servidor:

.venv/bin/python -m mcp_jira

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

Ejemplos de uso

Creación de incidencias

"Crea un error de alta prioridad porque el sistema de inicio de sesión no funciona correctamente"

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

Gestión de sprints

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

• Obtiene un informe de progreso completo 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 los elementos completados, en curso y bloqueados

Integración con 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: Utiliza 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 estándar MCP 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 electrónico de Jira

• JIRA_API_TOKEN - Tu token de API de Jira

• PROJECT_KEY - Clave de proyecto predeterminada para las operaciones (puede ser sobrescrita por solicitud)

Ajustes opcionales

• DEFAULT_BOARD_ID - Tablero predeterminado para operaciones de sprint (puede ser sobrescrito por solicitud)

• STORY_POINTS_FIELD - ID de campo personalizado para los 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 de Atlassian

2. Haz clic en "Crear token de API"

3. Dale un nombre y copia el token

4. Usa tu correo electrónico como nombre de usuario y el token como contraseña

Arquitectura

Esta implementación prioriza la simplicidad y la fiabilidad:

• Archivo de servidor MCP único - Todas las herramientas en un solo lugar

• Protocolo MCP estándar - Utiliza el SDK oficial de MCP

• API REST de Jira v3 - Utiliza el formato de documento de Atlassian (ADF) para las descripciones

• Formato enriquecido - Proporciona informes hermosos y legibles

• Reintento con retroceso - Maneja automáticamente los límites de tasa y los errores transitorios de la API de Jira

• Paginación - Obtiene todos los resultados para grandes conjuntos de incidencias

• Gestión de errores - Gestión 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 active sprint found"

   • Asegúrate de que tu tablero tenga un sprint activo

   • Comprueba 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 electrónico

3. Errores de permisos

   • Asegúrate de que tu usuario de Jira tenga los permisos de proyecto adecuados

   • Comprueba que la clave del proyecto exista y que tengas acceso

Modo de depuración

Establece DEBUG_MODE=true en tu archivo .env para obtener 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]"

3. Ejecuta las pruebas:

python -m pytest tests/ -v

4. Envía una solicitud de extracción (pull request)

Licencia

Licencia MIT - ver archivo LICENSE