Servidor MCP de JIRA

Una implementación de servidor del Model Context Protocol (MCP) que proporciona acceso a datos de JIRA con seguimiento de relaciones, cargas de datos optimizadas y limpieza de datos para ventanas de contexto de IA.

ℹ️ Hay un servidor MCP separado para Confluence

Soporte para Jira Cloud y Jira Server (Data Center)

Este servidor MCP admite tanto instancias de Jira Cloud como de Jira Server (Data Center). Puede seleccionar qué tipo utilizar configurando la variable de entorno JIRA_TYPE:

cloud (predeterminado): Para Jira Cloud (alojado por Atlassian)
server: Para Jira Server/Data Center (autohospedado)

El servidor utilizará automáticamente la versión correcta de la API y el método de autenticación para el tipo seleccionado.

Características

Buscar incidencias de JIRA usando JQL (máximo 50 resultados por solicitud)
Recuperar incidencias hijas de épicas con historial de comentarios y cargas optimizadas (máximo 100 incidencias por solicitud)
Obtener información detallada de incidencias, incluidos comentarios e incidencias relacionadas
Crear, actualizar y gestionar incidencias de JIRA
Añadir comentarios a las incidencias
Extraer menciones de incidencias del Formato de Documento de Atlassian
Realizar seguimiento de relaciones entre incidencias (menciones, enlaces, padre/hijo, épicas)
Limpiar y transformar contenido enriquecido de JIRA para eficiencia en el contexto de IA
Soporte para archivos adjuntos con manejo seguro de subidas multipart
Admite tanto las API de Jira Cloud como de Jira Server (Data Center)

Requisitos previos

Bun (v1.0.0 o superior)
Cuenta de JIRA con acceso a la API

Variables de entorno

JIRA_API_TOKEN=your_api_token            # API token for Cloud, PAT or password for Server/DC
JIRA_BASE_URL=your_jira_instance_url     # e.g., https://your-domain.atlassian.net
JIRA_USER_EMAIL=your_email               # Your Jira account email
JIRA_TYPE=cloud                          # 'cloud' or 'server' (optional, defaults to 'cloud')
JIRA_AUTH_TYPE=basic                     # 'basic' or 'bearer' (optional, defaults to 'basic')

Métodos de autenticación

Jira Cloud: Usar tokens de API con autenticación Basic
- Crear un token de API en: https://id.atlassian.com/manage-profile/security/api-tokens
- Establecer JIRA_AUTH_TYPE=basic (predeterminado)
Jira Server/Data Center:
- Autenticación Basic: Usar nombre de usuario/contraseña o tokens de API
  - Establecer JIRA_AUTH_TYPE=basic (predeterminado)
- Autenticación Bearer: Usar Tokens de Acceso Personal (PAT) - disponibles en Data Center 8.14.0+
  - Crear un PAT en la configuración de su perfil
  - Establecer JIRA_AUTH_TYPE=bearer
  - Usar el PAT como su JIRA_API_TOKEN

Instalación y configuración

1. Clonar el repositorio

git clone [repository-url]
cd jira-mcp

2. Instalar dependencias y compilar

bun install
bun run build

3. Configurar el servidor MCP

Edite el archivo de configuración correspondiente:

macOS:

Cline: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

Cline: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Claude Desktop: %APPDATA%\Claude Desktop\claude_desktop_config.json

Linux:

Cline: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Claude Desktop: lamentablemente aún no existe

Añada la siguiente configuración bajo el objeto mcpServers:

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["/absolute/path/to/jira-mcp/build/index.js"],
      "env": {
        "JIRA_API_TOKEN": "your_api_token",
        "JIRA_BASE_URL": "your_jira_instance_url",
        "JIRA_USER_EMAIL": "your_email",
        "JIRA_TYPE": "cloud",
        "JIRA_AUTH_TYPE": "basic"
      }
    }
  }
}

4. Reiniciar el servidor MCP

En la configuración MCP de Cline, reinicie el servidor MCP. Reinicie Claude Desktop para cargar el nuevo servidor MCP.

Desarrollo

Ejecutar pruebas:

bun test

Modo de observación para desarrollo:

bun run dev

Para recompilar después de cambios:

bun run build

Herramientas MCP disponibles

search_issues

Buscar incidencias de JIRA usando JQL. Devuelve hasta 50 resultados por solicitud.

Esquema de entrada:

{
  searchString: string; // JQL search string
}

get_epic_children

Obtener todas las incidencias hijas de una épica, incluidos sus comentarios y datos de relaciones. Limitado a 100 incidencias por solicitud.

Esquema de entrada:

{
  epicKey: string; // The key of the epic issue
}

get_issue

Obtener información detallada de una incidencia de JIRA específica, incluidos comentarios y todas las relaciones.

Esquema de entrada:

{
  issueId: string; // The ID or key of the JIRA issue
}

create_issue

Crear una nueva incidencia de JIRA con los campos especificados.

Esquema de entrada:

{
  projectKey: string, // The project key where the issue will be created
  issueType: string, // The type of issue (e.g., "Bug", "Story", "Task")
  summary: string, // The issue summary/title
  description?: string, // Optional issue description
  fields?: { // Optional additional fields
    [key: string]: any
  }
}

update_issue

Actualizar campos de una incidencia de JIRA existente.

Esquema de entrada:

{
  issueKey: string, // The key of the issue to update
  fields: { // Fields to update
    [key: string]: any
  }
}

add_attachment

Añadir un archivo adjunto a una incidencia de JIRA.

Esquema de entrada:

{
  issueKey: string, // The key of the issue
  fileContent: string, // Base64 encoded file content
  filename: string // Name of the file to be attached
}

add_comment

Añadir un comentario a una incidencia de JIRA. Acepta texto plano y lo convierte internamente al Formato de Documento de Atlassian requerido.

Esquema de entrada:

{
  issueIdOrKey: string, // The ID or key of the issue to add the comment to
  body: string // The content of the comment (plain text)
}

Características de limpieza de datos

Extrae texto del Formato de Documento de Atlassian
Realiza seguimiento de menciones de incidencias en descripciones y comentarios
Mantiene enlaces de incidencias formales con tipos de relación
Preserva relaciones padre/hijo
Realiza seguimiento de asociaciones con épicas
Incluye historial de comentarios con información del autor
Elimina metadatos innecesarios de las respuestas
Procesa recursivamente nodos de contenido para menciones
Deduplica menciones de incidencias

Detalles técnicos

Construido con TypeScript en modo estricto
Usa el runtime de Bun para un mejor rendimiento
Vite para compilaciones optimizadas
Usa la API REST de JIRA v3 (Cloud) o v2 (Server/Data Center)
Admite múltiples métodos de autenticación:
- Autenticación Basic con tokens de API o nombre de usuario/contraseña
- Autenticación Bearer con Tokens de Acceso Personal (PAT)
Solicitudes de API por lotes para datos relacionados
Cargas de respuesta optimizadas para ventanas de contexto de IA
Transformación eficiente de estructuras complejas de Atlassian
Manejo robusto de errores
Consideraciones de limitación de velocidad
Límites máximos:
- Resultados de búsqueda: 50 incidencias por solicitud
- Incidencias hijas de épicas: 100 incidencias por solicitud
Soporte para datos de formulario multipart para archivos adjuntos seguros
Detección y validación automática de tipo de contenido

Manejo de errores

El servidor implementa una estrategia integral de manejo de errores:

Detección de errores de red y mensajes apropiados
Manejo de códigos de estado HTTP (especialmente 404 para incidencias)
Mensajes de error detallados con códigos de estado
Registro de detalles de errores en la consola
Validación de entrada para todos los parámetros
Propagación segura de errores a través del protocolo MCP
Manejo especializado de errores comunes de la API de JIRA
Validación Base64 para archivos adjuntos
Manejo de fallos en solicitudes multipart
Detección de limitación de velocidad
Validación de parámetros de archivos adjuntos

LICENCIA

Este proyecto está licenciado bajo la Licencia MIT - consulte el archivo LICENCE para más detalles.

JIRA

Documentación