jira-easy-mcp

Jira Server/Data Center 7-10 autoalojado para agentes de IA con nombre de usuario y contraseña. 42 herramientas.

Documentación

jira-easy-mcp

Otro servidor de Model Context Protocol (MCP) para Jira, sin token de autenticación. Proporciona herramientas para la automatización completa de Jira, incluyendo incidencias, proyectos, tableros, sprints, comentarios, registros de trabajo y más.

Probado en: Jira Server / Data Center 7.13, 8.20, 9.12 y 10.3 (cada herramienta, automatizado, ver Desarrollo y Pruebas)

🔑 ¿Por qué este MCP?

Funciona con autenticación básica (usuario + contraseña) — ¡no se requieren tokens de API!

La mayoría de los servidores MCP de Jira requieren OAuth o tokens de API, que muchas organizaciones restringen o no permiten. Este MCP utiliza autenticación básica HTTP, por lo que puedes conectarte usando solo tu nombre de usuario y contraseña de Jira. Perfecto para:

🏢 Entornos empresariales donde los administradores no permiten la creación de tokens de API
🔒 Instancias de Jira Server autoalojadas sin OAuth configurado
⚡ Configuración rápida sin pasar por procesos de aprobación de TI

Inicio Rápido

VS Code (Configuración del Espacio de Trabajo)

Crea .vscode/mcp.json en la raíz de tu espacio de trabajo:

{
  "servers": {
    "jira": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "jira-easy-mcp"],
      "env": {
        "JIRA_BASE_URL": "https://your-jira-instance.com",
        "JIRA_USERNAME": "your-username",
        "JIRA_PASSWORD": "your-password",
        "JIRA_PROJECTS_FILTER": "ABC,DEF,XYZ",
        "JIRA_RESPONSE_FORMAT": "JSON"
      }
    }
  }
}

Agrégalo a la configuración de VS Code para acceder desde todos los espacios de trabajo.

Nota: JIRA_PROJECTS_FILTER y JIRA_RESPONSE_FORMAT son opcionales. El filtro de proyectos limita el acceso a los proyectos especificados. El formato de respuesta puede ser JSON (predeterminado) o TOON (notación orientada a texto).

Claude Code

claude mcp add jira \
  -e JIRA_BASE_URL=https://your-jira-instance.com \
  -e JIRA_USERNAME=your-username \
  -e JIRA_PASSWORD=your-password \
  -- npx -y jira-easy-mcp

Codex CLI

Agrégalo a ~/.codex/config.toml:

[mcp_servers.jira]
command = "npx"
args = ["-y", "jira-easy-mcp"]
env = { JIRA_BASE_URL = "https://your-jira-instance.com", JIRA_USERNAME = "your-username", JIRA_PASSWORD = "your-password" }

Otros clientes

Cursor: ~/.cursor/mcp.json o .cursor/mcp.json (usa el envoltorio "mcpServers": { ... })
Windsurf: Agrégalo a la configuración MCP de Windsurf (usa el envoltorio "mcpServers": { ... })
Claude Desktop: Edita claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\; usa el envoltorio "mcpServers": { ... })
Gemini CLI: ~/.gemini/settings.json (usa el envoltorio "mcpServers": { ... })

Todos usan la misma configuración de command, args y env que VS Code arriba.

Windows: si el cliente no puede iniciar npx, usa "command": "cmd" con "args": ["/c", "npx", "-y", "jira-easy-mcp"].

Límites de herramientas: algunos clientes (notablemente Cursor) limitan cuántas herramientas envían al modelo, históricamente alrededor de 40 en todos los servidores. Este servidor tiene 41; desactiva las que no necesites en la configuración MCP del cliente.

Credenciales desde el llavero del sistema operativo (opcional)

Para mantener tu contraseña fuera de los archivos de configuración, omite JIRA_USERNAME/JIRA_PASSWORD y almacena una credencial bajo el nombre de servicio JiraMCP:

macOS: security add-generic-password -s JiraMCP -a your-username -w (solicita la contraseña; en el primer inicio macOS pedirá permiso para que node la lea)
Windows: cmdkey /generic:JiraMCP /user:your-username /pass (usa /generic, no /add)

Si hay varias cuentas almacenadas, establece JIRA_USERNAME para elegir una. Cuando tanto JIRA_USERNAME como JIRA_PASSWORD están configurados, se usan y el llavero no se lee. El soporte del llavero usa el paquete opcional keytar; si no se puede instalar en tu máquina, usa las variables de entorno.

Casos de Uso Comunes

Tarea	Herramienta	Ejemplo de Prompt
Buscar incidencias	`jira_search`	"Busca todos los errores abiertos asignados a mí en el proyecto ABC"
Obtener detalles de incidencia	`jira_get_issue`	"Muéstrame los detalles de la incidencia ABC-123"
Ver imágenes de incidencia	`jira_get_issue_images`	"Muéstrame las capturas de pantalla adjuntas a ABC-123"
Subir adjunto	`jira_upload_attachment`	"Adjunta /Users/me/Desktop/error.png a ABC-123"
Crear incidencia	`jira_create_issue`	"Crea un nuevo error en el proyecto ABC con el título 'El botón de inicio de sesión no funciona'"
Actualizar incidencia	`jira_update_issue`	"Cambia la prioridad de ABC-123 a Alta y asígnala a john.doe"
Editar campos personalizados	`jira_update_issue` + `jira_get_edit_meta`	"Establece Severidad en ABC-123 como Crítica" (nombre único o id `customfield_`)
Agregar comentario	`jira_add_comment`	"Agrega un comentario a ABC-123 diciendo 'Corrección desplegada a staging'"
Cambiar estado	`jira_transition_issue`	"Mueve ABC-123 a Hecho"
Registrar tiempo	`jira_add_worklog`	"Registra 2 horas de trabajo en ABC-123 para ayer"
Listar proyectos	`jira_get_projects`	"Muéstrame todos los proyectos a los que tengo acceso"
Ver sprints	`jira_get_sprints`	"¿Qué hay en el sprint actual del proyecto ABC?"
Vincular incidencias	`jira_create_link`	"Vincula ABC-123 como bloqueador de ABC-124"
Generar URL de filtro	`jira_generate_filter_url`	"Crea un enlace compartible para todos los errores abiertos actualizados en los últimos 7 días"

Pruebas con MCP Inspector

El MCP Inspector proporciona una interfaz web para probar todas las herramientas de forma interactiva:

npx @modelcontextprotocol/inspector npx jira-easy-mcp

Esto abre un navegador en http://localhost:6274 donde puedes:

Ver todas las herramientas disponibles
Probar cada herramienta con parámetros personalizados
Ver las respuestas JSON sin procesar

Nota: Coloca estos valores dentro de la interfaz del inspector antes de conectarte: JIRA_BASE_URL, JIRA_USERNAME, JIRA_PASSWORD.

Campos personalizados

La API REST de Jira v2 identifica los campos personalizados por id (customfield_10006). Los valores son el payload REST sin procesar para ese tipo de campo. Los nombres mostrados funcionan solo cuando son únicos (exactos, sensibles a mayúsculas) en la pantalla relevante.

Lectura (`jira_get_issue`)

Respuesta predeterminada: campos del sistema más campos personalizados que actualmente tienen un valor, cada uno como { "id", "name", "value" }. Los comentarios, registros de trabajo y adjuntos se omiten a menos que pases include: ["comments"] (y/o worklogs, attachments). Los campos personalizados nulos se omiten a menos que customFields: "all" o pases fields.

fields reduce la obtención de campos personalizados (ids como customfield_11205, o nombres únicos de pantalla de edición como Severity). Los campos solicitados se devuelven incluso cuando son nulos. Los nombres provienen del expand=names de esta incidencia, no de GET /field.

{
  "key": "ABC-123",
  "customFields": [
    { "id": "customfield_10006", "name": "Story Points", "value": 5 },
    { "id": "customfield_10107", "name": "Flagged", "value": { "value": "Yes" } }
  ]
}

Escritura (`jira_update_issue` / `jira_create_issue`)

Pasa customFields con clave por id (customfield_10006) o por un nombre único de jira_get_edit_meta / jira_get_create_meta. Los ids no necesitan una obtención adicional. Los nombres se resuelven contra los metadatos de ese tipo de incidencia; los nombres duplicados fallan de forma segura (usa el id). No llames a jira_get_fields antes de cada escritura.

Esquema `type`	Valor REST
string / number / date	`"text"`, `5`, `"2011-10-03"`
option (select)	`{ "value": "Yes" }` o `{ "id": "10100" }`
user (Server)	`{ "name": "username" }` — no Cloud `accountId`
array de opciones	`[{ "value": "A" }, { "value": "B" }]` (`itemsType`: `option`)
limpiar	`null`

Un campo listado por jira_get_fields pero ausente en los metadatos de edición/creación no está en esa pantalla y no se puede actualizar.

Búsqueda (`jira_search`)

La búsqueda predeterminada devuelve solo campos del sistema (sin campos personalizados, sin volcados de comentarios/registros de trabajo/adjuntos). fields es extras aditivos: las claves del sistema y los ids customfield_ pasan; los nombres mostrados se resuelven con un GET /field en vivo sin caché. Prefiere los ids. Los nombres ambiguos fallan de forma segura.

Catálogo (`jira_get_fields`)

Úsalo para nombres de cláusulas JQL, no como paso previo para cada creación/actualización. Para campos en un tipo de incidencia, usa jira_get_edit_meta o jira_get_create_meta.

Variables de Entorno Opcionales

Variable	Predeterminado	Descripción
`JIRA_PROJECTS_FILTER`	(ninguno)	Claves de proyecto separadas por comas. Las herramientas rechazan claves de incidencia/proyecto fuera de la lista (los ids de incidencia deben darse como claves) y JQL se limita a estos proyectos. Los ids de tablero, sprint y enlace no se verifican
`JIRA_RESPONSE_FORMAT`	`JSON`	Formato de respuesta: `JSON` o `TOON`
`JIRA_LOG_LEVEL`	`INFO`	Verbosidad del registro: `DEBUG`, `INFO`, `WARN`, `ERROR`
`JIRA_TIMEOUT`	`30000`	Tiempo de espera de solicitud en milisegundos
`JIRA_RETRY_COUNT`	`3`	Reintentos para tiempos de espera, 429 y 502-504. Las solicitudes de escritura (POST) solo se reintentan en 429, por lo que un Jira lento nunca genera incidencias, comentarios o enlaces duplicados
`JIRA_RETRY_DELAY`	`1000`	Retraso base entre reintentos (ms)
`JIRA_SSL_VERIFY`	`true`	Establece en `false` para omitir la verificación SSL. Para una CA de empresa, prefiere `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`
`JIRA_CACHE_TTL`	`300`	TTL de caché en segundos para datos estáticos

jira_get_issue_images descarga imágenes a través de las URLs de adjuntos autenticados de Jira (/secure/attachment/..., Jira Server/Data Center). Devuelve hasta cinco imágenes por predeterminado (máximo diez), con un límite de 10 MiB por imagen y 20 MiB por respuesta. jira_upload_attachment lee un archivo local por ruta absoluta en la máquina que ejecuta el servidor.

Solución de Problemas

Error	Solución
`Authentication failed ... restart the MCP server`	Credenciales incorrectas. Después del primer fallo, el servidor deja de iniciar sesión, por lo que los reintentos repetidos del agente no pueden activar el bloqueo CAPTCHA de Jira. Corrige las credenciales y reinicia el servidor (o recarga los servidores MCP en tu cliente).
`Login blocked by CAPTCHA`	Demasiados inicios de sesión fallidos. Inicia sesión en Jira una vez en un navegador y luego reintenta.
`Jira redirected to ...`	`JIRA_BASE_URL` está desactivado: usa `https://` si Jira redirige allí, o agrega la ruta de contexto. Una redirección a una página de inicio de sesión significa que hay un proxy SSO frente a Jira.
`No Jira REST API at ...`	Generalmente falta la ruta de contexto, por ejemplo `https://host/jira` en lugar de `https://host`.
`fetch failed` / errores de certificado	CA de empresa: inicia el servidor con `NODE_EXTRA_CA_CERTS=/path/to/ca.pem`. Último recurso: `JIRA_SSL_VERIFY=false`.
`... outside the allowed projects`	La clave no está en `JIRA_PROJECTS_FILTER`.

Desarrollo y Pruebas

pnpm install
pnpm test              # unit tests + build (any OS, Node 18+)
node scripts/smoke.mjs # MCP handshake check (needs JIRA_BASE_URL set to anything)

Contra un Jira real (Docker, Node 20.10+): el asistente inicia un Jira desechable, completa la configuración con la licencia de bomba de tiempo pública de 3 horas de Atlassian, y siembra un administrador (admin / Jira-IT-admin-1), un segundo usuario y dos proyectos Scrum (IT, OT).

pnpm jira:up 9.12 8080            # or 7.13, 8.20, 10.3 (Jira 10 also starts PostgreSQL)
JIRA_IT_BASE_URL=http://localhost:8080 pnpm test:integration
pnpm jira:down 9.12

pnpm jira:up 9.12 8080 /jira sirve Jira bajo una ruta de contexto. Cada instancia necesita alrededor de 3 GB de memoria Docker; ejecuta una a la vez en máquinas pequeñas. Las pruebas del llavero solo se ejecutan donde keytar funciona y no existe una credencial real de JiraMCP, y eliminan lo que crean. CI ejecuta las pruebas unitarias en Linux, macOS y Windows (Node 18-24) y la suite de integración contra cada versión anterior.

Compatibilidad

Versión de Jira	Estado
Jira Server 7.12.1 / 7.12.3	✅ Probado manualmente
Jira Server 7.13	✅ Automatizado (todas las herramientas)
Jira Server / DC 8.20	✅ Automatizado (todas las herramientas)
Jira DC 9.12 (también bajo una ruta de contexto `/jira`)	✅ Automatizado (todas las herramientas)
Jira DC 10.3	✅ Automatizado (todas las herramientas)
Jira Cloud	︖ No probado (usa el MCP oficial)

Requiere Node.js 18+. CI ejecuta las pruebas unitarias y de humo MCP en macOS, Linux y Windows (Node.js 18–24).

Puedes mejorar esto reportando problemas

jira-easy-mcp

Documentación

jira-easy-mcp

🔑 ¿Por qué este MCP?

Inicio Rápido

VS Code (Configuración del Espacio de Trabajo)

Claude Code

Codex CLI

Otros clientes

Credenciales desde el llavero del sistema operativo (opcional)

Casos de Uso Comunes

Pruebas con MCP Inspector

Campos personalizados

Lectura (jira_get_issue)

Escritura (jira_update_issue / jira_create_issue)

Búsqueda (jira_search)

Catálogo (jira_get_fields)

Variables de Entorno Opcionales

Solución de Problemas

Desarrollo y Pruebas

Compatibilidad

Lectura (`jira_get_issue`)

Escritura (`jira_update_issue` / `jira_create_issue`)

Búsqueda (`jira_search`)

Catálogo (`jira_get_fields`)