Atlassian Jira

Integra IA con Atlassian Jira para gestionar proyectos, buscar incidencias y ver información de desarrollo como commits y pull requests.

GitHub
72

Documentación

Conecta IA a tus Proyectos de Jira

Transforma la forma en que gestionas y haces seguimiento de tu trabajo conectando Claude, Cursor AI y otros asistentes de IA directamente a tus proyectos, incidencias y flujos de trabajo de Jira. Obtén información instantánea de tus proyectos, optimiza la gestión de incidencias y mejora la colaboración de tu equipo.

NPM Version

Lo que puedes hacer

  • Pregunta a la IA sobre tus proyectos: "¿Cuáles son las incidencias activas en el proyecto DEV?"
  • Obtén información de incidencias: "Muéstrame los detalles de PROJ-123 incluyendo comentarios"
  • Haz seguimiento del progreso del proyecto: "Lista todas las incidencias de alta prioridad asignadas a mí"
  • Gestiona comentarios de incidencias: "Añade un comentario a PROJ-456 sobre los resultados de las pruebas"
  • Busca entre proyectos: "Encuentra todos los bugs en progreso en mis proyectos"
  • Crea y actualiza incidencias: "Crea un nuevo bug en el proyecto MOBILE"

Ideal para

  • Desarrolladores que necesitan acceso rápido a los detalles de incidencias y contexto de desarrollo
  • Gestores de proyectos que hacen seguimiento del progreso, prioridades y asignaciones del equipo
  • Scrum Masters que gestionan sprints y estados de flujo de trabajo
  • Líderes de equipo que supervisan la salud del proyecto y la resolución de incidencias
  • Ingenieros de QA que hacen seguimiento de bugs y estado de pruebas
  • Cualquier persona que quiera interactuar con Jira usando lenguaje natural

Inicio rápido

Ponte en marcha en 2 minutos:

1. Obtén tus credenciales de Jira

Genera un token de API de Jira:

  1. Ve a Atlassian API Tokens
  2. Haz clic en Create API token
  3. Asígnale un nombre como "AI Assistant"
  4. Copia el token generado inmediatamente (¡no lo volverás a ver!)

2. Pruébalo al instante

# Set your credentials
export ATLASSIAN_SITE_NAME="your-company"  # for your-company.atlassian.net
export ATLASSIAN_USER_EMAIL="your.email@company.com"
export ATLASSIAN_API_TOKEN="your_api_token"

# List your Jira projects
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# Get details about a specific project
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/DEV"

# Get an issue with JMESPath filtering
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/issue/PROJ-123" --jq "{key: key, summary: fields.summary, status: fields.status.name}"

Conéctate a asistentes de IA

Para usuarios de Claude Desktop

Añade esto a tu archivo de configuración de Claude (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Reinicia Claude Desktop y verás el servidor jira en la barra de estado.

Para otros asistentes de IA

La mayoría de los asistentes de IA son compatibles con MCP. Instala el servidor globalmente:

npm install -g @aashari/mcp-server-atlassian-jira

Luego configura tu asistente de IA para usar el servidor MCP con transporte STDIO.

Alternativa: archivo de configuración

Crea ~/.mcp/configs.json para la configuración a nivel de sistema:

{
  "jira": {
    "environments": {
      "ATLASSIAN_SITE_NAME": "your-company",
      "ATLASSIAN_USER_EMAIL": "your.email@company.com",
      "ATLASSIAN_API_TOKEN": "your_api_token"
    }
  }
}

Claves de configuración alternativas: El sistema también acepta "atlassian-jira", "@aashari/mcp-server-atlassian-jira" o "mcp-server-atlassian-jira" en lugar de "jira".

Herramientas disponibles

Este servidor MCP proporciona 5 herramientas genéricas que pueden acceder a cualquier endpoint de la API de Jira:

HerramientaDescripción
jira_getGET a cualquier endpoint de la API de Jira (leer datos)
jira_postPOST a cualquier endpoint (crear recursos)
jira_putPUT a cualquier endpoint (reemplazar recursos)
jira_patchPATCH a cualquier endpoint (actualizaciones parciales)
jira_deleteDELETE a cualquier endpoint (eliminar recursos)

Rutas de API comunes

Proyectos:

  • /rest/api/3/project/search - Listar todos los proyectos (paginado, recomendado)
  • /rest/api/3/project - Listar todos los proyectos (no paginado, heredado)
  • /rest/api/3/project/{projectKeyOrId} - Obtener detalles del proyecto

Incidencias:

  • /rest/api/3/search/jql - Buscar incidencias con JQL (usar el parámetro de consulta jql). IMPORTANTE: ¡/rest/api/3/search está obsoleto!
  • /rest/api/3/issue/{issueIdOrKey} - Obtener detalles de la incidencia
  • /rest/api/3/issue - Crear incidencia (POST)
  • /rest/api/3/issue/{issueIdOrKey}/transitions - Obtener/realizar transiciones

Comentarios:

  • /rest/api/3/issue/{issueIdOrKey}/comment - Listar/añadir comentarios
  • /rest/api/3/issue/{issueIdOrKey}/comment/{commentId} - Obtener/actualizar/eliminar comentario

Registros de trabajo:

  • /rest/api/3/issue/{issueIdOrKey}/worklog - Listar/añadir registros de trabajo
  • /rest/api/3/issue/{issueIdOrKey}/worklog/{worklogId} - Obtener/actualizar/eliminar registro de trabajo

Usuarios y estados:

  • /rest/api/3/myself - Obtener usuario actual
  • /rest/api/3/user/search - Buscar usuarios (usar el parámetro query)
  • /rest/api/3/status - Listar todos los estados
  • /rest/api/3/issuetype - Listar tipos de incidencia
  • /rest/api/3/priority - Listar prioridades

Formato de salida TOON

Por defecto, todas las respuestas usan el formato TOON (Token-Oriented Object Notation), que reduce el uso de tokens entre un 30 y un 60 % en comparación con JSON. TOON utiliza matrices tabulares y sintaxis mínima, lo que lo hace ideal para el consumo por parte de IA.

Para usar JSON en su lugar: Añade --output-format json a los comandos CLI o establece outputFormat: "json" en las llamadas de herramientas MCP.

Ejemplo de TOON vs JSON:

TOON: key|summary|status
      PROJ-1|First issue|Open
      PROJ-2|Second issue|Done

JSON: [{"key":"PROJ-1","summary":"First issue","status":"Open"},
       {"key":"PROJ-2","summary":"Second issue","status":"Done"}]

Filtrado con JMESPath

Todas las herramientas admiten filtrado opcional con JMESPath (jq) para extraer datos específicos:

# Get just project names and keys
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/project/search" \
  --jq "values[].{key: key, name: name}"

# Get issue key and summary
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

Truncamiento de respuestas y registros sin procesar

Para respuestas de API grandes (>40 000 caracteres ≈ 10 000 tokens), las respuestas se truncan automáticamente con orientación. La respuesta sin procesar completa se guarda en /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt como referencia.

Cuando se trunca, verás:

  • Un aviso de truncamiento con la ruta del archivo sin procesar
  • Sugerencias para refinar tu consulta con mejores filtros
  • Porcentaje de datos mostrados frente al tamaño total

Ejemplos del mundo real

Explora tus proyectos

Pregunta a tu asistente de IA:

  • "Lista todos los proyectos a los que tengo acceso"
  • "Muéstrame los detalles del proyecto DEV"
  • "¿Qué proyectos contienen la palabra 'Platform'?"

Busca y haz seguimiento de incidencias

Pregunta a tu asistente de IA:

  • "Encuentra todas las incidencias de alta prioridad en el proyecto DEV"
  • "Muéstrame las incidencias asignadas a mí que estén en progreso"
  • "Busca bugs reportados en la última semana"
  • "Lista todas las incidencias abiertas del equipo móvil"

Gestiona detalles de incidencias

Pregunta a tu asistente de IA:

  • "Obtén todos los detalles de la incidencia PROJ-456 incluyendo comentarios"
  • "¿Cuál es el estado actual y el responsable de PROJ-123?"
  • "Muestra todos los comentarios sobre el bug de autenticación"

Comunicación sobre incidencias

Pregunta a tu asistente de IA:

  • "Añade un comentario a PROJ-456: 'Revisión de código completada, lista para pruebas'"
  • "Comenta en la incidencia de inicio de sesión que se ha desplegado en staging"

Comandos CLI

La CLI replica las herramientas MCP para acceso directo desde la terminal:

# GET request (returns TOON format by default)
npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/project/search"

# GET with query parameters and JSON output
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "project=DEV AND status=\"In Progress\"", "maxResults": "10"}' \
  --output-format json

# GET with JMESPath filtering to extract specific fields
npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/issue/PROJ-123" \
  --jq "{key: key, summary: fields.summary, status: fields.status.name}"

# POST request (create an issue)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue" \
  --body '{"fields": {"project": {"key": "DEV"}, "summary": "New issue title", "issuetype": {"name": "Task"}}}'

# POST request (add a comment)
npx -y @aashari/mcp-server-atlassian-jira post \
  --path "/rest/api/3/issue/PROJ-123/comment" \
  --body '{"body": {"type": "doc", "version": 1, "content": [{"type": "paragraph", "content": [{"type": "text", "text": "My comment"}]}]}}'

# PUT request (update issue - full replacement)
npx -y @aashari/mcp-server-atlassian-jira put \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# PATCH request (partial update)
npx -y @aashari/mcp-server-atlassian-jira patch \
  --path "/rest/api/3/issue/PROJ-123" \
  --body '{"fields": {"summary": "Updated title"}}'

# DELETE request
npx -y @aashari/mcp-server-atlassian-jira delete \
  --path "/rest/api/3/issue/PROJ-123/comment/12345"

Nota: Todos los comandos CLI admiten:

  • --output-format - Elige entre toon (predeterminado, eficiente en tokens) o json
  • --jq - Filtra la respuesta con expresiones JMESPath
  • --query-params - Pasa parámetros de consulta como cadena JSON

Solución de problemas

"Authentication failed" o "403 Forbidden"

  1. Comprueba los permisos de tu token de API:

  2. Verifica el formato de tu nombre de sitio:

    • Si tu URL de Jira es https://mycompany.atlassian.net
    • Tu nombre de sitio debería ser solo mycompany

  3. Prueba tus credenciales:

    npx -y @aashari/mcp-server-atlassian-jira get --path "/rest/api/3/myself"

"Resource not found" o "404"

  1. Comprueba la ruta de la API:

    • Las rutas distinguen entre mayúsculas y minúsculas
    • Usa claves de proyecto (p. ej., DEV) en lugar de nombres de proyecto
    • Las claves de incidencia incluyen el prefijo del proyecto (p. ej., DEV-123)

  2. Verifica los permisos de acceso:

    • Asegúrate de tener acceso al proyecto en tu navegador
    • Algunos proyectos pueden estar restringidos a ciertos usuarios

"No results found" al buscar

  1. Prueba con términos de búsqueda diferentes:

    • Usa claves de proyecto en lugar de nombres de proyecto
    • Prueba con criterios de búsqueda más amplios

  2. Comprueba la sintaxis de JQL:

    • Valida tu JQL en la búsqueda avanzada de Jira primero

Problemas de integración con Claude Desktop

  1. Reinicia Claude Desktop después de actualizar el archivo de configuración
  2. Verifica la ubicación del archivo de configuración:
    • macOS: ~/.claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json

Obtener ayuda

Si sigues teniendo problemas:

  1. Ejecuta un comando de prueba simple para verificar que todo funciona
  2. Consulta GitHub Issues para ver problemas similares
  3. Crea una nueva incidencia con tu mensaje de error y los detalles de configuración

Preguntas frecuentes

¿Qué permisos necesito?

Tu cuenta de Atlassian necesita:

  • Acceso a Jira con los permisos adecuados para los proyectos que quieras consultar
  • Token de API con los permisos apropiados (se otorgan automáticamente al crearlo)

¿Puedo usarlo con Jira Server (on-premise)?

Actualmente, esta herramienta solo es compatible con Jira Cloud. El soporte para Jira Server/Data Center podría añadirse en versiones futuras.

¿Cómo encuentro mi nombre de sitio?

Tu nombre de sitio es la primera parte de tu URL de Jira:

  • URL: https://mycompany.atlassian.net -> Nombre de sitio: mycompany
  • URL: https://acme-corp.atlassian.net -> Nombre de sitio: acme-corp

¿Con qué asistentes de IA funciona?

Con cualquier asistente de IA que admita el Model Context Protocol (MCP):

  • Claude Desktop
  • Cursor AI
  • Continue.dev
  • Muchos otros

¿Mis datos están seguros?

¡Sí! Esta herramienta:

  • Se ejecuta completamente en tu máquina local
  • Usa tus propias credenciales de Jira
  • Nunca envía tus datos a terceros
  • Solo accede a lo que le des permiso de acceder

¿Puedo buscar en varios proyectos?

¡Sí! Usa consultas JQL para búsquedas entre proyectos. Por ejemplo:

npx -y @aashari/mcp-server-atlassian-jira get \
  --path "/rest/api/3/search/jql" \
  --query-params '{"jql": "assignee=currentUser() AND status=\"In Progress\""}'

Detalles técnicos

Actualizaciones recientes

Versión 3.2.1 (diciembre de 2025):

  • Se añadió el formato de salida TOON para una reducción de tokens del 30-60 %
  • Se implementó el truncamiento automático de respuestas para cargas útiles grandes (>40 000 caracteres)
  • Las respuestas de API sin procesar se guardan en /tmp/mcp/mcp-server-atlassian-jira/ como referencia
  • Se actualizó al MCP SDK v1.23.0 con la API moderna registerTool
  • Se corrigió el endpoint obsoleto /rest/api/3/search (ahora usa /rest/api/3/search/jql)
  • Se actualizaron todas las dependencias a las versiones más recientes (Zod v4.1.13, Commander v14.0.2)

Requisitos

  • Node.js: 18.0.0 o superior
  • MCP SDK: v1.23.0 (usa APIs de registro modernas)
  • Jira: solo Cloud (no compatible con Server/Data Center)

Arquitectura

Este servidor sigue la arquitectura MCP de 5 capas:

  1. Capa CLI - Interfaz humana usando Commander.js
  2. Capa de herramientas - Interfaz de IA con validación Zod
  3. Capa de controladores - Lógica de negocio y orquestación
  4. Capa de servicios - Llamadas directas a la API REST de Jira
  5. Capa de utilidades - Preocupaciones transversales (registro, formato, transporte)

Depuración

Habilita el registro de depuración estableciendo la variable de entorno DEBUG:

# In Claude Desktop config
{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@aashari/mcp-server-atlassian-jira"],
      "env": {
        "DEBUG": "true",
        "ATLASSIAN_SITE_NAME": "your-company",
        "ATLASSIAN_USER_EMAIL": "your.email@company.com",
        "ATLASSIAN_API_TOKEN": "your_api_token"
      }
    }
  }
}

Los registros de depuración se escriben en ~/.mcp/data/mcp-server-atlassian-jira.<session-id>.log

Comprueba las respuestas de API sin procesar: Cuando las respuestas se truncan, la respuesta sin procesar completa se guarda en /tmp/mcp/mcp-server-atlassian-jira/<timestamp>-<random>.txt con los detalles de solicitud/respuesta.

Migración desde v2.x

La versión 3.0 reemplaza más de 8 herramientas específicas por 5 herramientas genéricas de métodos HTTP. Si estás actualizando desde v2.x:

Antes (v2.x):

jira_ls_projects, jira_get_project, jira_ls_issues, jira_get_issue,
jira_create_issue, jira_ls_comments, jira_add_comment, jira_ls_statuses, ...

Después (v3.0+):

jira_get, jira_post, jira_put, jira_patch, jira_delete

Ejemplos de migración:

  • jira_ls_projects -> jira_get con la ruta /rest/api/3/project/search
  • jira_get_project -> jira_get con la ruta /rest/api/3/project/{key}
  • jira_get_issue -> jira_get con la ruta /rest/api/3/issue/{key}
  • jira_create_issue -> jira_post con la ruta /rest/api/3/issue
  • jira_add_comment -> jira_post con la ruta /rest/api/3/issue/{key}/comment
  • jira_ls_statuses -> jira_get con la ruta /rest/api/3/status

Ventajas de v3.0+:

  • Acceso completo a cualquier endpoint de la API REST v3 de Jira (no solo herramientas predefinidas)
  • Filtrado JMESPath para una extracción de datos eficiente
  • Interfaz coherente en todos los métodos HTTP
  • Formato TOON para ahorrar entre un 30 y un 60 % de tokens
  • Truncamiento automático de respuestas con registro de archivos sin procesar

Soporte

¿Necesitas ayuda? Así puedes obtener asistencia:

  1. Consulta la sección de solución de problemas anterior - la mayoría de los problemas comunes se cubren allí
  2. Visita nuestro repositorio de GitHub para documentación y ejemplos: github.com/aashari/mcp-server-atlassian-jira
  3. Reporta problemas en GitHub Issues
  4. Inicia una discusión para solicitudes de funciones o preguntas generales

Hecho con cuidado para equipos que quieren llevar la IA a su flujo de trabajo de gestión de proyectos.