Servidor MCP de Jira para Claude Code

Un servidor completo del Protocolo de Contexto de Modelos (MCP) para la integración de Jira con Claude Code. Este servidor proporciona una funcionalidad completa de Jira, incluyendo gestión de incidencias, operaciones de sprint, comentarios, archivos adjuntos y procesamiento por lotes.

License: MIT TypeScript Node.js

⚠️ Nota de seguridad: ¡Nunca subas tus tokens de API! Utiliza variables de entorno (por ejemplo, en ~/.zshrc) o gestión de secretos.

🚀 Características

📋 Gestión de incidencias (12 herramientas)

create-issue - Crea incidencias con soporte completo de campos, incluyendo campos personalizados y fechas
update-issue - Actualiza incidencias existentes con manejo inteligente de campos
get-issue - Recupera información detallada de una incidencia
search-issues - Búsqueda avanzada usando JQL o filtros simplificados con soporte de fechas
transition-issue - Mueve incidencias a través de los estados del flujo de trabajo
link-issues - Crea relaciones entre incidencias (con coincidencia inteligente de tipos)
get-link-types - Lista los tipos de enlaces de incidencia disponibles
get-fields - Muestra los campos disponibles para un proyecto/tipo de incidencia
diagnose-fields - Soluciona problemas de configuración de campos y encuentra IDs de campos personalizados
create-epic-with-subtasks - Crea una épica con múltiples subtareas en una sola operación
create-task-for-epic - Crea una tarea vinculada a una épica (optimizado para Jira localizado)

💬 Comentarios e historial (3 herramientas)

get-comments - Lee comentarios de incidencias con información del autor y marca de tiempo
get-history - Visualiza el historial detallado de cambios con modificaciones de campos
add-comment - Añade comentarios con soporte para el formato de documento de Atlassian (ADF)
batch-comment - Añade el mismo comentario a múltiples incidencias simultáneamente

📎 Archivos adjuntos (2 herramientas)

get-attachments - Lista archivos adjuntos con metadatos (tamaño, tipo, fecha de subida)
upload-attachment - Sube archivos usando codificación base64

🏃 Gestión de Sprints y Agile (4 herramientas)

get-boards - Lista los tableros de Jira disponibles para proyectos ágiles
get-sprints - Visualiza los sprints de un tablero con indicadores de estado
move-issue-to-sprint - Mueve incidencias entre sprints y el backlog
create-sprint - Crea nuevos sprints con fechas de inicio/fin opcionales

Recursos

jira://projects - Lista todos los proyectos accesibles
jira://project/{key} - Obtiene detalles específicos de un proyecto
jira://issue/{key} - Obtiene detalles específicos de una incidencia
jira://myself - Información del usuario actual
jira://search?jql={query} - Resultados de búsqueda

Prompts

standup-report - Genera informes diarios de standup
sprint-planning - Asiste en actividades de planificación de sprint
bug-triage - Ayuda a priorizar y clasificar errores (bugs)
release-notes - Genera notas de lanzamiento a partir de incidencias completadas
epic-status - Informes completos de progreso de épicas

Instalación

Clona el repositorio:

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

Instala las dependencias:

npm install

Compila el proyecto:

npm run build

Configura tus credenciales de Jira en las variables de entorno (por ejemplo, ~/.zshrc):

Para Jira Cloud:

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

Para Jira Server/DC 9.12+:

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

Para Jira Server/DC (legado):

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

Consulta docs/AUTH_SETUP.md para obtener la guía completa de autenticación.

Obtención de credenciales

Jira Cloud (Token de API)

Inicia sesión en la configuración de cuenta de Atlassian
Haz clic en "Create API token"
Dale un nombre (por ejemplo, "MCP Server")
Copia el token y añádelo a la configuración de tu shell (por ejemplo, ~/.zshrc) como JIRA_API_TOKEN

Jira Server/DC 9.12+ (Token de acceso personal)

Inicia sesión en Jira Server/DC
Ve a Perfil → Tokens de acceso personal
Haz clic en Crear token
Establece el nombre y la expiración (máximo 365 días)
Copia el token inmediatamente: no se podrá volver a ver
Añádelo a la configuración de tu shell (por ejemplo, ~/.zshrc) como JIRA_PAT

Consulta docs/AUTH_SETUP.md para obtener instrucciones detalladas de configuración.

Configuración de Claude Code

Para usar este servidor MCP con Claude Code, debes configurarlo en tus ajustes de MCP.

Opción 1: Usar variables de entorno (Recomendado)

Configura el servidor con variables de entorno en tu configuración de shell (por ejemplo, ~/.zshrc):

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

Opción 2: Añadir a los ajustes de Claude Code

Añade el servidor a tu archivo de ajustes de Claude Code (~/.claude/settings.json):

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

Ejemplos de uso

Creación de incidencias

Create a new bug in project PROJ with high priority about login issues

Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

Establecer fechas y estimaciones de tiempo

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"

Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"

Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

Creación de épicas con subtareas

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

Creación de subtareas

Create a subtask "Review code" for parent issue PROJ-123

Soporte para Jira en checo

Create issue type "Úkol" in project PROJ

Create task for epic PPC-48 with summary "Database backup"

Búsqueda de incidencias

Find all open bugs assigned to me

Search for issues in project PROJ with label "urgent" that are not done

Búsqueda basada en fechas

Search issues due before "next week" in project PROJ

Find issues created after "2024-12-01" and updated after "yesterday"

Search for overdue issues: dueBefore "today" and status != "Done"

Gestión de incidencias

Update PROJ-123 to add story points 8

Transition PROJ-456 to "In Progress"

Link PROJ-123 to PROJ-456 as "blocks"

Nota: Las relaciones Épica-Historia usan el campo epicLink, no enlaces de incidencia normales:

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

Uso de Prompts

Generate a standup report for john@example.com

Help me plan the sprint for project PROJ

Create release notes for version 2.0 in project PROJ

Configuración avanzada

Campos personalizados

El servidor puede trabajar con cualquier configuración de Jira:

Opción 1: Detección automática (Recomendado)

Deja los IDs de campos personalizados sin configurar en tu entorno y el servidor los detectará automáticamente basándose en los nombres de los campos.

Opción 2: Configuración manual

Si la detección automática no funciona, configura los IDs de campos personalizados en tu entorno (por ejemplo, ~/.zshrc):

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

Encontrar IDs de campos

Usa la herramienta diagnose-fields para encontrar los IDs de campo correctos para tu instancia de Jira:

diagnose-fields project:"PROJ" issueType:"Story"

Creación automática de tickets de prueba

Habilita la creación automática de tickets de prueba para historias:

AUTO_CREATE_TEST_TICKETS=true

Desarrollo

Ejecución en modo desarrollo

npm run dev

Verificación de tipos

npm run typecheck

Linting

npm run lint

Características

🌍 Soporte de localización

Soporte automático para instancias de Jira localizadas (checo, inglés, etc.)
Los nombres de los tipos de incidencia pueden estar en cualquier idioma (por ejemplo, "Task", "Úkol", "Aufgabe")
Los nombres de prioridad soportan localización (por ejemplo, "High", "Vysoká", "Hoch")
Soporte especial para configuraciones de Jira en checo
Funciona con cualquier configuración de idioma de Jira

📅 Gestión de fecha y hora

Formatos de entrada de fecha flexibles:
- ISO: "2024-12-31"
- Europeo: "31.12.2024" o "31/12/2024"
- Relativo: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"
- Checo: "dnes", "zítra", "příští týden"
Soporte de seguimiento de tiempo:
- Estimaciones: "2h", "1d 4h", "3 days", "2 hodiny"
- Conversión automática de formato
Búsqueda y filtrado basados en fechas

🔄 Reintento automático

El servidor reintenta automáticamente las solicitudes fallidas con retroceso exponencial (hasta 3 intentos).

📦 Manejo robusto de errores

Manejo de respuestas vacías para transiciones de Jira
Mensajes de error detallados con contexto
Degradación elegante para funciones faltantes

📝 Registro completo (Logging)

Habilita el registro de depuración para ver información detallada:

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 Prueba de conexión

El servidor prueba la conexión al iniciarse y proporciona mensajes de error claros si la autenticación falla.

📄 Formato de documento de Atlassian (ADF)

Convierte automáticamente texto plano y markdown al formato ADF de Jira para campos de texto enriquecido.

Solución de problemas

Trabajar con diferentes configuraciones de Jira

Este servidor MCP está diseñado para funcionar con cualquier instancia de Jira independientemente de:

Configuración de idioma (inglés, checo, alemán, etc.)
Configuraciones de campos personalizados
Configuraciones específicas del proyecto

Mejores prácticas:

Usa get-fields para ver los tipos de incidencia disponibles en tu idioma
Usa diagnose-fields para encontrar IDs de campos personalizados
Crea incidencias usando los nombres exactos de los tipos de incidencia de tu Jira

Problemas comunes

Error de autenticación
- Verifica que tu token de API sea correcto
- Asegúrate de que tu correo electrónico coincida con tu cuenta de Atlassian
- Comprueba que la URL de tu instancia de Jira incluya https://
Proyecto no encontrado
- Verifica que tienes acceso al proyecto
- Comprueba que la clave del proyecto sea correcta (distingue entre mayúsculas y minúsculas)
Los campos personalizados no funcionan
- Usa la herramienta diagnose-fields para encontrar los IDs de campo correctos para tu proyecto
- Usa la herramienta get-fields para ver todos los campos disponibles
- Los IDs de campos personalizados suelen empezar por customfield_
- Algunos campos pueden no estar disponibles para ciertos tipos de incidencia (por ejemplo, etiquetas en épicas)
- El ID del campo Epic Link varía entre instancias de Jira
Tipo de enlace no encontrado
- Usa la herramienta get-link-types para ver los tipos de enlace disponibles
- Los tipos de enlace distinguen entre mayúsculas y minúsculas en la API de Jira
- El servidor intentará hacer coincidir sin distinguir entre mayúsculas y minúsculas
- Las relaciones Épica-Historia usan el campo epicLink, no enlaces de incidencia normales
Problemas de vinculación Épica-Historia
- Ejecuta diagnose-fields para el proyecto y el tipo de incidencia "Story"
- Actualiza JIRA_FIELD_EPIC_LINK en tu configuración de entorno con el ID de campo correcto
- Reinicia tu terminal o ejecuta source ~/.zshrc después de actualizar

Modo de depuración

Establece la variable de entorno DEBUG para un registro detallado:

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

Ver registros

Los registros se envían a stderr e incluyen:

Estado de la conexión
Solicitudes y respuestas de la API
Detalles de errores con contexto
Métricas de rendimiento

Contribución

Consulta CONTRIBUTING.md para conocer las directrices de desarrollo.

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles

Soporte

Para problemas y solicitudes de funciones, utiliza el rastreador de incidencias de GitHub.