jira-mcp-server

ybreff/jira-mcp-server

3.1

If you are the rightful owner of jira-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

A Model Context Protocol (MCP) server for Jira integration that facilitates interaction with Jira's API through structured tools.

Tools
7
Resources
0
Prompts
0

Jira MCP Server

Un servidor MCP (Model Context Protocol) para integración con Jira que permite interactuar con la API de Jira a través de herramientas estructuradas.

📋 Descripción

Este proyecto implementa un servidor MCP que actúa como intermediario entre aplicaciones compatibles con MCP y la API REST de Jira. Permite realizar operaciones comunes de Jira como crear, actualizar, buscar issues y gestionar proyectos de manera programática.

🚀 Características

  • ✅ Gestión completa de issues: Crear, leer, actualizar y buscar issues
  • ✅ Búsqueda avanzada: Soporte completo para JQL (Jira Query Language)
  • ✅ Gestión de comentarios: Agregar comentarios a issues existentes
  • ✅ Información de proyectos: Obtener detalles completos de proyectos
  • ✅ Transiciones de estado: Consultar y ejecutar transiciones de workflow
  • ✅ TypeScript: Completamente tipado para mejor desarrollo
  • ✅ Manejo de errores: Logging detallado y manejo robusto de errores
  • ✅ Autenticación segura: Soporte para API tokens de Jira

🛠️ Tecnologías

  • Node.js >= 18.0.0
  • TypeScript 5.3+
  • Axios para llamadas HTTP
  • @modelcontextprotocol/sdk para el protocolo MCP

📦 Instalación

1. Clonar el repositorio

git clone <url-del-repositorio>
cd jira-mcp-server

2. Instalar dependencias

npm install

3. Configurar variables de entorno

Crear un archivo .env en la raíz del proyecto:

JIRA_BASE_URL=https://tu-dominio.atlassian.net
JIRA_USERNAME=tu-email@ejemplo.com
JIRA_API_TOKEN=tu-api-token-de-jira
Generar token de API en Jira:

  1. Ve a tu perfil de Atlassian

  2. Security → API tokens

    • En el menú lateral, selecciona "Security"
    • Haz clic en "API tokens"

  3. Crea un nuevo token

    • Clic en "Create API token"
    • Asigna un nombre descriptivo (ej: "jira-mcp-server")
    • Clic en "Create"

  4. Guárdalo en las variables de entorno

    • Copia el token generado inmediatamente (no podrás verlo nuevamente)
    • Pégalo en tu archivo .env como valor de JIRA_API_TOKEN

⚠️ Importante: El token solo se muestra una vez. Si lo pierdes, deberás generar uno nuevo.

4. Compilar el proyecto

npm run build

5. Ejecutar el servidor

npm start

🔧 Scripts disponibles

npm run build     # Compilar TypeScript a JavaScript
npm run start     # Ejecutar el servidor compilado
npm run dev       # Modo desarrollo con watch
npm run clean     # Limpiar archivos compilados
npm run type-check # Verificar tipos sin compilar
npx -y @modelcontextprotocol/inspector npx -y tsx src/index.ts # Abre un inspector en el navegador para probar el mcp-server

🛠️ Herramientas disponibles

El servidor MCP expone las siguientes herramientas:

1. get_issue

Obtiene información completa de un issue específico.

Parámetros:

  • issueKey (string, requerido): Clave del issue (ej: "PROJ-123")

Ejemplo de uso:

{
  "name": "get_issue",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}

2. create_issue

Crea un nuevo issue en Jira.

Parámetros:

  • projectKey (string, requerido): Clave del proyecto
  • summary (string, requerido): Resumen del issue
  • issueType (string, requerido): Tipo de issue (Bug, Story, Task, Epic, etc.)
  • description (string, opcional): Descripción detallada
  • priority (string, opcional): Prioridad (Highest, High, Medium, Low, Lowest)
  • assignee (string, opcional): Usuario asignado (username o email)
  • labels (array, opcional): Etiquetas del issue
  • duedate (string, opcional): Fecha de vencimiento (YYYY-MM-DD)

Ejemplo de uso:

{
  "name": "create_issue",
  "arguments": {
    "projectKey": "PROJ",
    "summary": "Nuevo bug encontrado",
    "issueType": "Bug",
    "description": "Descripción detallada del bug",
    "priority": "High",
    "assignee": "usuario@ejemplo.com"
  }
}

3. update_issue

Actualiza un issue existente.

Parámetros:

  • issueKey (string, requerido): Clave del issue a actualizar
  • summary (string, opcional): Nuevo resumen
  • description (string, opcional): Nueva descripción
  • status (string, opcional): Nuevo estado (usar nombre del estado)
  • assignee (string, opcional): Nuevo asignado
  • priority (string, opcional): Nueva prioridad
  • labels (array, opcional): Nuevas etiquetas
  • duedate (string, opcional): Nueva fecha de vencimiento

4. search_issues

Busca issues usando JQL (Jira Query Language).

Parámetros:

  • jql (string, requerido): Query JQL para buscar issues
  • maxResults (number, opcional): Número máximo de resultados (default: 50)
  • startAt (number, opcional): Índice del primer resultado (default: 0)

Ejemplo de uso:

{
  "name": "search_issues",
  "arguments": {
    "jql": "project = PROJ AND status = 'In Progress'",
    "maxResults": 25
  }
}

5. add_comment

Agrega un comentario a un issue.

Parámetros:

  • issueKey (string, requerido): Clave del issue
  • comment (string, requerido): Texto del comentario

6. get_project_info

Obtiene información completa de un proyecto.

Parámetros:

  • projectKey (string, requerido): Clave del proyecto

7. get_transitions

Obtiene las transiciones disponibles para un issue.

Parámetros:

  • issueKey (string, requerido): Clave del issue

📁 Estructura del proyecto

jira-mcp-server/
├── src/
│   ├── config/
│   │   └── jira.ts              # Configuración de conexión Jira
│   ├── server/
│   │   └── mcp-server.ts        # Implementación del servidor MCP
│   ├── services/
│   │   └── jira-api.ts          # Servicio de API de Jira
│   ├── types/
│   │   ├── args.ts              # Tipos de argumentos
│   │   └── jira.ts              # Tipos de datos de Jira
│   └── index.ts                 # Punto de entrada
├── build/                       # Archivos compilados
├── package.json
├── tsconfig.json
└── README.md

🔍 Ejemplos de uso con JQL

Buscar issues por proyecto y estado

project = MYPROJECT AND status = "In Progress"

Buscar bugs de alta prioridad

project = MYPROJECT AND issuetype = Bug AND priority = High

Buscar issues asignados a un usuario

assignee = "usuario@ejemplo.com" AND status != Done

Buscar issues creados en los últimos 7 días

project = MYPROJECT AND created >= -7d

🐛 Solución de problemas

Error de autenticación

  • Verifica que las variables de entorno estén configuradas correctamente
  • Asegúrate de que el API token sea válido y no haya expirado
  • Confirma que el usuario tenga permisos en el proyecto de Jira

Error de conexión

  • Verifica que la URL base de Jira sea correcta
  • Asegúrate de que el servidor Jira esté accesible
  • Revisa la conectividad de red

Issues con JQL

  • Valida la sintaxis JQL en la interfaz web de Jira
  • Verifica que los nombres de campos y valores sean correctos
  • Consulta la documentación oficial de JQL

📄 Licencia

MIT License - ver el archivo para detalles.

👨‍💻 Autor

Yasmany Breffpacheco

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor:

  1. Fork el proyecto
  2. Crea una rama para tu feature (git checkout -b feature/nueva-caracteristica)
  3. Commit tus cambios (git commit -am 'Agregar nueva característica')
  4. Push a la rama (git push origin feature/nueva-caracteristica)
  5. Abre un Pull Request

📚 Referencias

Configurar la IA para usar el servidor MCP

En el archivo de configuración de tu cliente MCP (como Claude Desktop):

{
  "mcpServers": {
    "jira": {
      "command": "node",
      "args": ["path/to/your/jira-mcp-server/build/index.js"],
      "env": {
        "JIRA_BASE_URL": "https://tu-dominio.atlassian.net",
        "JIRA_USERNAME": "tu-email@dominio.com",
        "JIRA_API_TOKEN": "tu-token-de-api"
      }
    }
  }
}
Funcionalidades disponibles
get_issue: Obtener información de un issue específico
create_issue: Crear nuevos issues
update_issue: Actualizar issues existentes
search_issues: Buscar issues con JQL
add_comment: Agregar comentarios
get_project_info: Información del proyecto
Ejemplos de uso

Una vez configurado, tu IA podrá:

"Muéstrame el issue PROJ-123"
"Crea un nuevo bug en el proyecto TEST con el resumen 'Error en login'"
"Busca todos los issues asignados a juan.perez"
"Agrega un comentario al issue PROJ-456 diciendo que está en revisión"