Skip to main content
Glama
deenesjakoruzh
vaspap1790

jira-mcp

by vaspap1790
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Jira MCP Server

Сервер протокола контекста модели (MCP), предоставляющий инструменты для взаимодействия с Jira. Позволяет Cursor и другим MCP-клиентам получать тикеты, управлять связанными тикетами и обновлять статус тикетов.

Быстрый старт

1. Установка зависимостей

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

# Install project dependencies
uv sync

2. Настройка учетных данных Jira

Рекомендуется: Токен личного доступа (PAT)

  1. Войдите в Jira: https://jira.telekom.de

  2. Перейдите в свой профиль > Personal Access Tokens

  3. Нажмите "Create token"

  4. Дайте ему имя (например, "Cursor MCP") и установите срок действия

  5. Важно: Убедитесь, что у токена есть права "Read" или "Browse Projects"

  6. Скопируйте токен сразу (вы не увидите его снова)

Создайте файл .env:

cp .env.example .env

Отредактируйте .env, указав свои учетные данные:

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

Примечание: Токены API Kantega SSO могут иметь IP-ограничения или требовать разрешений, настроенных администратором. Токены личного доступа рекомендуются для большинства пользователей.

3. Настройка в Cursor

  1. Откройте Cursor

  2. Перейдите в Settings > Tools and MCP

  3. Добавьте эту конфигурацию:

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

Важно: Замените путь и учетные данные на ваши фактические значения!

  1. Полностью перезапустите Cursor

4. Попробуйте в действии

В чате Cursor попробуйте:

  • "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

Функции

Доступные инструменты

Инструмент

Описание

Пример

get_ticket

Получить полные сведения о тикете

"Get PROJ-123"

get_linked_tickets

Получить связанные тикеты и подзадачи

"Show linked tickets for PROJ-123"

update_ticket_status

Обновить статус тикета

"Move PROJ-123 to In Progress"

Поддержка аутентификации

  • Bearer Token: Токены личного доступа (PAT) - Рекомендуется

  • Basic Auth: Имя пользователя + токен API (Atlassian Cloud)

  • Cookie Auth: Аутентификация на основе сессии (резервный вариант)

Подробности об инструментах

get_ticket

Получает полную информацию о тикете.

Параметры:

  • ticket_id (строка, обязательно): ID или ключ тикета (например, "PROJ-123")

Возвращает:

{
  "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

Получает все связанные тикеты и подзадачи.

Параметры:

  • ticket_id (строка, обязательно): ID или ключ тикета

Возвращает:

{
  "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

Обновляет статус тикета с проверкой рабочего процесса.

Параметры:

  • ticket_id (строка, обязательно): ID или ключ тикета

  • status (строка, обязательно): Целевой статус (например, "In Progress", "Done")

Возвращает:

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

Примечание: Инструмент проверяет переходы. Если переход недействителен, он возвращает доступные переходы.

Тестирование

Запуск тестов

# 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

Ручное тестирование

Протестируйте сервер напрямую:

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

Нажмите Ctrl+C для остановки.

Устранение неполадок

Ошибки аутентификации

Симптомы: "401 Unauthorized" или "403 Forbidden"

Решения:

  • Наиболее часто: Токен личного доступа истек - создайте новый

  • Проверьте, что ваш PAT имеет права "Read" или "Browse Projects"

  • Проверьте, что ваше имя пользователя совпадает с адресом электронной почты вашей учетной записи Jira

  • Убедитесь, что JIRA_URL включает https://

  • Подтвердите, что JIRA_AUTH_TYPE=bearer для токенов личного доступа

Тикет не найден

Симптомы: "404 Not Found"

Решения:

  • Проверьте правильность ключа тикета (например, "PROJ-123")

  • Проверьте, есть ли у вас разрешение на просмотр тикета

  • Убедитесь, что вы используете правильный экземпляр Jira

Сервер не появляется в Cursor

Решения:

  • Проверьте абсолютный путь в настройках MCP

  • Проверьте, установлен ли Python 3.12+: python3 --version

  • Полностью перезапустите Cursor (закройте и откройте снова)

  • Проверьте консоль разработчика Cursor на наличие ошибок

Невозможно изменить статус тикета

Симптомы: "Invalid status transition"

Решения:

  • Сообщение об ошибке содержит список доступных переходов

  • Имена статусов должны совпадать точно (регистронезависимо)

  • Проверьте разрешения вашего рабочего процесса Jira

  • Убедитесь, что переход действителен для вашего рабочего процесса

Архитектура

Этот проект следует принципам SOLID и чистой архитектуре:

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

Ключевые принципы:

  • SOLID: Единственная ответственность, инверсия зависимостей

  • DRY: Отсутствие дублирования, повторно используемые компоненты

  • Безопасность типов: Полные подсказки типов повсюду

  • Тестируемость: Четкое разделение ответственности

См. ARCHITECTURE.md для получения подробной технической документации.

Разработка

Структура проекта

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

Добавление зависимостей

uv add package-name

Запуск с другой конфигурацией

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

Качество кода

  • Ошибки линтинга: 0

  • Покрытие типами: 100%

  • Покрытие тестами: Интеграционные тесты для всех 3 инструментов

  • Архитектура: Соответствует SOLID + DRY

Требования

  • Python 3.12+

  • Учетная запись Jira с доступом к API

  • Токен API Jira (Kantega SSO Enterprise или Atlassian Cloud)

Лицензия

Этот проект предоставляется "как есть" для использования с Cursor и Jira.

Создано с использованием лучших практик, соответствующих принципам SOLID и 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
Pay for results, not tokens.Fund a bounty. Let AI agents compete and collaborate to solve your problems.agentbounties.appAd

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
ResponsivenessNo issues

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
    23 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
    -