Skip to main content
Glama
Sign In
deenesjakoruzh
jira-mcp

jira-mcp

by vaspap1790
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Servidor Jira MCP

Un servidor de Model Context Protocol (MCP) que proporciona herramientas para interactuar con Jira. Permite a Cursor y otros clientes MCP obtener tickets, gestionar tickets vinculados y actualizar el estado de los tickets.

Inicio rápido

1. Instalar dependencias

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install project dependencies
uv sync

2. Configurar las credenciales de Jira

Recomendado: Token de acceso personal (PAT)

  1. Inicia sesión en Jira: https://jira.telekom.de

  2. Ve a tu perfil > Personal Access Tokens

  3. Haz clic en "Create token"

  4. Dale un nombre (p. ej., "Cursor MCP") y establece una fecha de caducidad

  5. Importante: Asegúrate de que el token tenga permisos de "Read" o "Browse Projects"

  6. Copia el token inmediatamente (no volverás a verlo)

Crea el archivo .env:

cp .env.example .env

Edita .env con tus credenciales:

JIRA_URL=https://jira.telekom.de
JIRA_USERNAME=your.username@telekom.de
JIRA_API_TOKEN=your_personal_access_token_here
JIRA_AUTH_TYPE=bearer

Nota: Los tokens de API de Kantega SSO pueden tener restricciones de IP o requerir permisos configurados por el administrador. Los tokens de acceso personal son recomendados para la mayoría de los usuarios.

3. Configurar en Cursor

  1. Abre Cursor

  2. Ve a Settings > Tools and MCP

  3. Añade esta configuración:

{
  "mcpServers": {
    "jira": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/jira-mcp",
        "run",
        "-m",
        "src"
      ]
    }
  }
}

Importante: ¡Reemplaza la ruta y las credenciales con tus valores reales!

  1. Reinicia Cursor por completo

4. Pruébalo

En el chat de Cursor, intenta:

  • "Get details for Jira ticket PROJ-123"

  • "Show me all linked tickets for PROJ-456"

  • "Update PROJ-789 status to In Progress"

Related MCP server: JIRA MCP Server

Características

Herramientas disponibles

Herramienta

Descripción

Ejemplo

get_ticket

Obtener detalles completos del ticket

"Get PROJ-123"

get_linked_tickets

Obtener tickets relacionados y subtareas

"Show linked tickets for PROJ-123"

update_ticket_status

Actualizar el estado del ticket

"Move PROJ-123 to In Progress"

Soporte de autenticación

  • Bearer Token: Tokens de acceso personal (PAT) - Recomendado

  • Basic Auth: Nombre de usuario + Token de API (Atlassian Cloud)

  • Cookie Auth: Autenticación basada en sesión (opción de respaldo)

Detalles de las herramientas

get_ticket

Obtiene información completa del ticket.

Parámetros:

  • ticket_id (cadena, requerido): ID o clave del ticket (p. ej., "PROJ-123")

Retorna:

{
  "key": "PROJ-123",
  "summary": "Ticket summary",
  "description": "Detailed description",
  "status": "In Progress",
  "issue_type": "Story",
  "priority": "High",
  "assignee": "John Doe",
  "reporter": "Jane Smith",
  "created": "2024-01-15T10:30:00.000+0000",
  "updated": "2024-01-20T14:45:00.000+0000",
  "comments_count": 3,
  "comments": [...],
  "custom_fields": {...}
}

get_linked_tickets

Obtiene todos los tickets relacionados y subtareas.

Parámetros:

  • ticket_id (cadena, requerido): ID o clave del ticket

Retorna:

{
  "ticket": "PROJ-123",
  "linked_tickets": [
    {
      "link_type": "Blocks",
      "direction": "blocks",
      "key": "PROJ-124",
      "summary": "Related ticket",
      "status": "To Do"
    }
  ],
  "linked_tickets_count": 1,
  "subtasks": [...],
  "subtasks_count": 2
}

update_ticket_status

Actualiza el estado del ticket con validación de flujo de trabajo.

Parámetros:

  • ticket_id (cadena, requerido): ID o clave del ticket

  • status (cadena, requerido): Estado objetivo (p. ej., "In Progress", "Done")

Retorna:

Successfully updated ticket PROJ-123 status from 'To Do' to 'In Progress'

Nota: La herramienta valida las transiciones. Si no es válida, devuelve las transiciones disponibles.

Pruebas

Ejecutar pruebas

# Run all tests
.venv/bin/pytest tests/ -v

# Run with coverage
.venv/bin/pytest tests/ --cov=src -v

# Run specific test file
.venv/bin/pytest tests/test_integration/test_real_tickets.py -v

Pruebas manuales

Prueba el servidor directamente:

uv run --env-file .env -m src

Presiona Ctrl+C para detener.

Solución de problemas

Errores de autenticación

Síntomas: "401 Unauthorized" o "403 Forbidden"

Soluciones:

  • Lo más común: El token de acceso personal ha caducado; genera uno nuevo

  • Verifica que tu PAT tenga permisos de "Read" o "Browse Projects"

  • Comprueba que tu nombre de usuario coincida con el correo electrónico de tu cuenta de Jira

  • Asegúrate de que JIRA_URL incluya https://

  • Confirma JIRA_AUTH_TYPE=bearer para tokens de acceso personal

Ticket no encontrado

Síntomas: "404 Not Found"

Soluciones:

  • Verifica que la clave del ticket sea correcta (p. ej., "PROJ-123")

  • Comprueba que tienes permiso para ver el ticket

  • Asegúrate de estar usando la instancia de Jira correcta

El servidor no aparece en Cursor

Soluciones:

  • Verifica la ruta absoluta en tu configuración de MCP

  • Comprueba que Python 3.12+ esté instalado: python3 --version

  • Reinicia Cursor por completo (cierra y vuelve a abrir)

  • Revisa la consola de desarrollador de Cursor en busca de errores

No se puede realizar la transición del ticket

Síntomas: "Invalid status transition"

Soluciones:

  • El mensaje de error enumera las transiciones disponibles

  • Los nombres de estado deben coincidir exactamente (sin distinguir entre mayúsculas y minúsculas)

  • Comprueba tus permisos de flujo de trabajo de Jira

  • Verifica que la transición sea válida para tu flujo de trabajo

Arquitectura

Este proyecto sigue los principios SOLID y una arquitectura limpia:

src/
├── __init__.py
├── __main__.py           # Entry point
├── server.py             # MCP server setup
├── config/               # Configuration management
├── client/               # Jira API client
├── tools/                # 3 MCP tools
├── models/               # Domain models
├── mappers/              # Data transformation
└── utils/                # Error handling, JSON utils

Principios clave:

  • SOLID: Responsabilidad única, inversión de dependencia

  • DRY: Sin duplicación, componentes reutilizables

  • Seguridad de tipos: Sugerencias de tipo completas en todo el código

  • Testeable: Separación clara de responsabilidades

Consulta ARCHITECTURE.md para obtener documentación técnica detallada.

Desarrollo

Estructura del proyecto

jira-mcp/
├── src/                  # Source code (22 Python files)
├── tests/                # Test suite
├── pyproject.toml        # Project config (includes pytest config)
├── .env.example          # Config template
├── .gitignore
├── README.md             # This file
└── ARCHITECTURE.md       # Technical docs

Añadir dependencias

uv add package-name

Ejecutar con una configuración diferente

uv run --env-file .env.production -m src

Calidad del código

  • Errores de linting: 0

  • Cobertura de tipos: 100%

  • Cobertura de pruebas: Pruebas de integración para las 3 herramientas

  • Arquitectura: Cumple con SOLID + DRY

Requisitos

  • Python 3.12+

  • Cuenta de Jira con acceso a API

  • Token de API de Jira (Kantega SSO Enterprise o Atlassian Cloud)

Licencia

Este proyecto se proporciona tal cual para su uso con Cursor y Jira.

Construido con las mejores prácticas siguiendo los principios SOLID y DRY 🚀

Available Tools

3 tools
get_linked_ticketsA

Fetch all linked tickets and subtasks for a given Jira ticket. Returns issue links (blocks, is blocked by, relates to, etc.) and subtasks with their summaries and statuses.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.8/5.0
Behavior3/5

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

No annotations are provided, so the description carries the burden. It discloses what is returned (issue links and subtasks with summaries and statuses) but lacks details on authorization, pagination, or limits.

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 sentences, front-loaded with purpose followed by output details. No redundant information.

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?

Given one required parameter and no output schema, the description covers purpose, parameter, and return structure. It lacks error handling or clarification on depth of links, but is relatively complete for a simple fetch tool.

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?

Input schema coverage is 100% with a description of ticket_id. The description adds an example format ('e.g., 'PROJ-123'') but does not provide additional semantics beyond the 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?

The description clearly states the verb 'Fetch' and the resource 'all linked tickets and subtasks for a given Jira ticket', distinguishing it from siblings like get_ticket which returns a single ticket.

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

Usage Guidelines3/5

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

The description implies usage when needing linked tickets or subtasks, but does not explicitly state when to use this tool versus alternatives like get_ticket or update_ticket_status.

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

get_ticketA

Fetch full details of a Jira ticket by its ID or key. Returns comprehensive ticket information including summary, description, status, issue type, priority, assignee, reporter, comments, and custom fields.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')

TDQS

A3.6/5.0
Behavior3/5

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

No annotations provided. Description discloses that the tool fetches (read operation) and lists returned fields, but does not mention rate limits, required permissions, error cases, or side effects. It adds value over schema by specifying return contents but lacks full behavioral context.

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 sentences: first states action and input, second lists outputs. No extraneous words, front-loaded, and efficient.

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?

For a simple one-parameter tool with no output schema, the description provides a good overview of return content (summary, description, status, etc.). Minor gap: custom fields are vague and exact structure not detailed, but sufficient for basic understanding.

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?

Schema coverage is 100% with a description for ticket_id. The description reiterates 'by its ID or key' without adding new meaning beyond the schema's example. Hence, baseline score of 3.

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

Purpose4/5

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

The description clearly states it fetches full details of a Jira ticket by ID or key and lists returned information (summary, status, etc.). It distinguishes from sibling tools ('get_linked_tickets', 'update_ticket_status') implicitly by resource and verb, but does not explicitly contrast them.

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

Usage Guidelines3/5

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

The description implies when to use (when you need ticket details) but does not explicitly state when not to use or suggest alternatives like get_linked_tickets for linked issues.

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

update_ticket_statusA

Update the status of a Jira ticket by transitioning it to a new status. Validates that the transition is valid for the ticket's current workflow. Common statuses include: 'To Do', 'In Progress', 'In Review', 'Done'.

NameRequiredDescriptionDefault
ticket_idYesThe Jira ticket ID or key (e.g., 'PROJ-123')
statusYesThe target status name (e.g., 'In Progress', 'Done')

TDQS

A3.9/5.0
Behavior3/5

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

With no annotations, the description carries the burden. It mentions validation of transitions, but does not disclose side effects (e.g., notifications), permissions requirements, idempotency, or error handling behavior. This is adequate but not thorough.

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?

The description is two sentences, front-loaded with the action, and contains no redundant information. Every sentence contributes meaningful context.

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

Completeness3/5

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

Given the tool's simplicity (2 params, no nested objects), the description is mostly complete. However, it omits the return value or success/error behavior, which would be helpful since there is no output schema.

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?

Schema coverage is 100%, earning a baseline of 3. The description adds value by listing common statuses ('To Do', 'In Progress', 'In Review', 'Done'), which provides context beyond the schema's generic description.

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 the action ('Update the status of a Jira ticket by transitioning it to a new status') and differentiates from sibling read-only tools like 'get_linked_tickets' and 'get_ticket'. It also provides examples of common statuses, making the purpose unambiguous.

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

Usage Guidelines3/5

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

The description implies usage by mentioning validation of transitions, but does not explicitly state when to use or avoid this tool, nor does it provide alternatives beyond the obvious sibling tools. It lacks guidance on prerequisites or edge cases.

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.

  1. 3 tool updatesv0.1.0
    • First observedget_linked_tickets
    • First observedget_ticket
    • First observedupdate_ticket_status
Deploy Server
Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

TDQS

A3.8/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct operation: retrieving a ticket, fetching linked tickets, and updating status. No overlap in functionality.

Naming Consistency5/5

All tool names follow a consistent 'verb_noun' pattern in snake_case (get_ticket, get_linked_tickets, update_ticket_status), making them predictable.

Tool Count4/5

Three tools is on the lower end of the ideal range but still reasonable for a focused Jira server. Each tool serves a clear purpose without feeling sparse.

Completeness2/5

Missing essential CRUD operations such as create_ticket, search_tickets, or add_comment. Agents cannot create new tickets or perform most lifecycle actions.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers

  • JIRA MCP Server

    Dsazz
    A
    license
    B
    quality
    D
    maintenance
    A Model Context Protocol server that integrates JIRA directly into Cursor IDE, allowing users to view assigned issues, get detailed information on specific tickets, and convert JIRA issues into local tasks without leaving their editor.
    14
    28 npm
    6
    TypeScript
    MIT

  • Jira MCP Server

    maximepeabody
    A
    license
    Not graded
    quality
    D
    maintenance
    A Simple Model Context Protocol server that enables AI assistants to interact with Jira, allowing operations like fetching tickets, adding comments, and updating ticket status.
    1
    Apache 2.0

  • MCP Jira

    TusharShahi
    F
    license
    Not graded
    quality
    D
    maintenance
    Model Context Protocol server that allows AI assistants to interact with Jira, supporting operations like creating tickets and fetching project information directly from the cursor.
    1
    -