Skip to main content
Glama
lfern

jira-gateway

by lfern
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

jira-gateway

MCP local que expone 3 acciones al agente: list_my_tasks, create_task (con confirmación obligatoria en dos pasos) y start_task. Alcance deliberadamente reducido a Jira — git (rama, commits, push, historial) lo sigue manejando Claude Code directamente por bash, como ya hacías. Este gateway no intenta ser una barrera para git; solo cubre lo que el agente no puede hacer por sí mismo: hablar con Jira sin ver tus credenciales.

Instalación

Requiere Python >=3.11. Si tu Python de sistema es más antiguo, usa uv para que te instale un 3.11 aislado en el propio .venv sin tocar nada del sistema:

curl -LsSf https://astral.sh/uv/install.sh | sh
cd jira-git-gateway
uv venv --python 3.11
source .venv/bin/activate
uv pip install -e .

(Alternativa sin uv, si ya tienes Python 3.11+ disponible en el sistema: python3 -m venv .venv && source .venv/bin/activate && pip install -e .)

Related MCP server: jayrah

Configuración (variables de entorno)

Crea ~/.jira-gateway.env (fuera de este repo — la ruta exacta es configurable con JIRA_GATEWAY_ENV_FILE si quieres otra):

JIRA_EMAIL=tu-email@dominio.com
JIRA_API_TOKEN=el-token-con-scope-write:jira-work-y-read:jira-work
JIRA_CLOUD_ID=...           # GET https://tudominio.atlassian.net/_edge/tenant_info
JIRA_SITE_URL=https://tudominio.atlassian.net
JIRA_PROJECT_KEY=PROJ
JIRA_IN_PROGRESS_STATUS=In Progress  # opcional, ajusta al nombre real de tu workflow
JIRA_SELECTED_STATUS=Selected for Development  # opcional, estado al que pasa create_task tras crear
JIRA_DEFAULT_ISSUE_TYPE=Task  # opcional, ajusta al nombre real de tu tipo de issue
JIRA_SUBTASK_ISSUE_TYPE=Subtask  # opcional, tipo usado al crear con parent_key sin issue_type explícito

gateway/config.py lo carga solo (vía python-dotenv) al arrancar —no hace falta exportarlo en tu shell ni pasarlo por la config de MCP. Motivo de que viva fuera del repo: así no está a la vista dentro del directorio que Claude Code tiene abierto mientras curras. No es una barrera de seguridad dura —un agente con Bash sin restricciones podría igualmente leer esa ruta si se lo propone— pero evita la exposición accidental y evita duplicar el token en ~/.claude.json al configurar el MCP. Si quieres una barrera más fuerte (un usuario Unix separado que de verdad no pueda leer el token), usa el modo servicio de la sección de abajo.

Añadirlo a Claude Code

Hay dos formas de conectarlo. Ojo: en ambas, Claude Code corre con tu mismo usuario del sistema, así que cualquier cosa que ese usuario pueda leer (incluido un .env en el propio repo, o la config de MCP donde metas el token) el agente también puede leerla por Bash si se lo propone — el subproceso stdio no es una barrera real contra eso, solo una forma cómoda de que el agente no necesite tocar el token para hacer su trabajo normal.

Opción A — stdio (rápida, sin aislamiento real de credenciales)

Como ~/.jira-gateway.env ya lo carga el propio config.py, aquí no hace falta pasar ningún env — así el token tampoco queda duplicado dentro de ~/.claude.json:

{
  "mcpServers": {
    "jira-gateway": {
      "command": "/ruta/a/jira-git-gateway/.venv/bin/python",
      "args": ["-m", "gateway.server"]
    }
  }
}

(No hace falta cwd: el paquete queda instalado en modo editable en el venv, así que -m gateway.server funciona desde cualquier directorio.)

Vale para uso personal en el que confías en que el agente usa las tools porque son el camino natural para lo que le pides, no porque no tenga forma de saltárselas.

Opción B — servicio systemd bajo usuario separado (aislamiento real)

scripts/setup_service.sh despliega el gateway bajo un usuario Unix dedicado (jira-gw, sin login), con el .env en /opt/jira-gateway/.env (modo 600, propiedad de jira-gw) — tu usuario normal no puede leerlo ni por cat ni por ninguna otra vía, porque no tiene permisos de sistema sobre esos ficheros. El gateway corre como servicio (streamable-http) y Claude Code se conecta por red, sin ver el token en ningún momento:

sudo bash scripts/setup_service.sh

Y en la config de Claude Code, sin credenciales:

{
  "mcpServers": {
    "jira-gateway": {
      "type": "http",
      "url": "http://127.0.0.1:8765/mcp"
    }
  }
}

Es más montaje (usuario de sistema, systemd, redeploy con el script cuando cambies código), pero es la única de las dos opciones donde "el agente no puede leer el token" es una garantía técnica y no solo una expectativa de buen comportamiento.

Flujo de uso

  1. "¿Qué tareas tengo pendientes?" → list_my_tasks

  2. "Crea una tarea para X" → create_task (sin confirm) → el agente te enseña el preview (proyecto, tipo, resumen, descripción, etiquetas) → si dices que sí, el agente vuelve a llamar a create_task con confirm=True y los mismos datos → ahí sí se crea. Acepta labels opcional (lista de strings) para etiquetar el issue al crearlo.

  3. "Selecciona la PROJ-123 para desarrollo" → start_task con status="Selected for Development" (o el nombre exacto de la transición intermedia de tu workflow).

  4. "Empieza la PROJ-123" → start_task sin status → transiciona al estado de "en progreso" configurado en JIRA_IN_PROGRESS_STATUS.

  5. Claude Code crea la rama, desarrolla, comitea y hace push con sus herramientas normales de bash/git — el gateway no interviene en nada de esto, y puede seguir leyendo git log/git diff/git blame sin restricción alguna.

  6. Tú abres el PR a mano cuando toque.

Nota sobre la confirmación: además del preview de create_task, Claude Code ya te pide aprobación antes de ejecutar cualquier llamada a un MCP no auto-aprobado (verás el JSON de parámetros antes de que se dispare). El preview de create_task es una capa extra pensada para que la revisión sea legible (texto formateado) en vez de JSON crudo — como cuando revisas el mensaje de un commit antes de confirmarlo.

Por qué está diseñado así

  • Catálogo cerrado de tools: solo 2 acciones, ambas de Jira, ninguna toca git. No hay "ejecuta este comando" genérico ni JQL libre.

  • Git queda fuera a propósito: ya confías en Claude Code para manejar git por bash (commits, push, y también lectura de historial cuando lo necesitas), así que el gateway no intenta duplicar ni restringir eso — solo cubre lo que el agente no puede hacer solo, que es hablar con Jira sin ver tu token.

  • Validación de issue_key (PROJ-123) antes de tocar Jira.

  • create_task nunca escribe en la primera llamada: el flag confirm empieza en False por defecto, así que la ruta "segura" (preview) es la que sale sin que nadie tenga que acordarse de pedirla explícitamente.

  • start_task solo transiciona issues asignados a ti: comprueba el assignee contra el usuario del token antes de tocar nada. Si el issue es de otra persona (o está sin asignar), falla sin transicionar. Esto no aplica a la transición automática de create_task a JIRA_SELECTED_STATUS, ya que un issue recién creado normalmente está aún sin asignar.

Notas

  • No he podido instalar/testear mcp en el entorno donde escribí esto (sin red). Antes de usarlo en serio, pásalo por tu Claude Code local para que compile, corra pip install -e . y valide el import — probablemente haga falta algún ajuste menor de API si tu versión de mcp difiere.

  • El scope de token recomendado: clásico write:jira-work + read:jira-work (los granulares de escritura tienen un bug conocido en POST a fecha de hoy — ver conversación anterior).

Available Tools

3 tools
create_taskA

Crea una tarea nueva en Jira en el proyecto configurado. Tras crearla la mueve automáticamente al estado JIRA_SELECTED_STATUS (por defecto 'Selected for Development'), así no se queda parada en Backlog.

IMPORTANTE: llama primero SIN confirm (o con confirm=False). Eso no crea nada, solo devuelve una vista previa de lo que se enviaría — muéstrasela al usuario tal cual. Solo si el usuario la aprueba, vuelve a llamar con confirm=True para crearla de verdad.

ParametersJSON Schema
NameRequiredDescriptionDefault
labelsNo
confirmNo
summaryYes
issue_typeNo
descriptionNo

TDQS

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Al no haber anotaciones, la descripción asume la carga completa. Revela que la herramienta mueve automáticamente la tarea a un estado específico (JIRA_SELECTED_STATUS) y detalla el comportamiento del parámetro confirm (preview sin creación, ejecución con confirm=True).

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

La descripción es breve (4 oraciones), con la información más importante al inicio. Cada oración aporta valor: propósito, comportamiento automático y el flujo de confirmación. No hay redundancia.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Aunque falta un esquema de salida, la descripción cubre bien el comportamiento principal. Sin embargo, no menciona qué devuelve (por ejemplo, los detalles de la tarea creada) ni posibles errores o requisitos previos. Aun así, es suficiente para un uso básico.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

La cobertura de descripción del esquema es 0%. La descripción solo explica el parámetro confirm en detalle; los demás (summary, labels, issue_type, description) no se describen más allá de sus nombres. Aunque los nombres son autoexplicativos, la falta de aclaración reduce la puntuación.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

El verbo 'crear' y el recurso 'tarea' son específicos. La descripción indica claramente que crea una tarea en Jira en el proyecto configurado, lo que la distingue de los hermanos 'list_my_tasks' y 'start_task'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

La descripción instruye explícitamente que primero se llame sin confirm (o con confirm=False) para obtener una vista previa, y solo si el usuario aprueba, se llame con confirm=True. Esto indica cuándo y cómo usar la herramienta de forma segura.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_my_tasksA

Lista tus tareas asignadas y no cerradas en el proyecto configurado. Solo lectura. No acepta JQL ni parámetros: el filtro está fijado.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Clearly declares read-only behavior and that filter is fixed with no parameters. No annotations provided, so description carries burden well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no superfluous information; every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and presence of output schema, description fully specifies scope and constraints (assigned, not closed, configured project, read-only).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters; description reinforces that no JQL or parameters are accepted, adding clarity beyond the empty schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'list' and resource 'tasks' with specific filter (assigned and not closed). Distinguishes from siblings by noting read-only and no parameters.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description indicates it is read-only with a fixed filter, implying when to use it (viewing tasks) vs. siblings (create/start). Could explicitly mention alternatives but context suffices.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

start_taskA

Transiciona el issue indicado en Jira. Sin status, lo pasa al estado de 'en progreso' configurado (JIRA_IN_PROGRESS_STATUS). Con status, transiciona a ese estado en su lugar (debe coincidir, sin distinguir mayúsculas, con el nombre exacto de una transición disponible en el workflow del issue, ej. 'Selected for Development') — útil para pasos previos a empezar a desarrollar. Solo funciona si el issue está asignado a ti; si no, devuelve error sin tocar nada. No toca git: la rama, el desarrollo, el commit y el push los gestiona Claude Code directamente con sus herramientas de siempre.

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNo
issue_keyYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses key behaviors: only works if issue assigned to user, returns error without changes otherwise, and states it does not touch git. With no annotations, description carries full burden and covers important side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise Spanish description, front-loads the main action, no wasted sentences. Every sentence serves a purpose: action, parameter explanation, prerequisite, side-effect note.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a Jira transition tool with moderate complexity. Covers default status, custom transitions, assignment requirement, and clarifies no git involvement. No output schema, but behavior is well explained.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Specifies 'issue_key' is required and explains 'status': default to configured in-progress, or use a custom transition name. Adds meaning beyond schema (which has 0% coverage), though could mention expected format of 'issue_key'.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it transitions an issue in Jira, specifying the default action (move to 'in progress') and the optional custom status. It distinguishes from siblings: 'create_task' (create) and 'list_my_tasks' (list).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides clear context: use when starting work on an issue, with guidance on the 'status' parameter for pre-development steps. Implicitly excludes when not assigned (returns error) and mentions no git interaction, but no explicit when-not-to-use or alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 3 tool updatesv0.1.0
    • First observedcreate_task
    • First observedlist_my_tasks
    • First observedstart_task
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.4/5.0
Disambiguation5/5

Each tool has a clearly distinct purpose: creating tasks, listing assigned tasks, and transitioning task status. No overlap exists.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: create_task, list_my_tasks, start_task.

Tool Count4/5

Three tools is a minimal but reasonable set for a Jira gateway focusing on task creation, listing, and status transitions.

Completeness3/5

Core create, read, and transition operations are covered, but missing update, delete, and advanced querying limit completeness for typical Jira workflows.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • jayrah

    chmouel
    A
    license
    Not graded
    quality
    F
    maintenance
    Enables AI assistants to interact with Jira via CLI/TUI, supporting issue browsing, creation, comments, status changes, and custom fields.
    3
    Apache 2.0

  • mcp-jira-scoped

    deepwired
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to manage Jira tasks, issues, and projects using Atlassian's modern scoped API tokens, with safety features like read-only default and delete confirmation.
    88
    3
    Apache 2.0

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lfern/jira-gateway-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server