Интеграция MCP с Jira

Простой сервер Model Context Protocol (MCP) для Jira, который позволяет LLM выступать в роли менеджеров проектов и личных помощников для команд, использующих Jira. Построен на базе Jira REST API v3.

Возможности

Основные инструменты MCP

• create_issue — создание новых задач в Jira с правильным форматированием и описаниями в формате ADF

• search_issues — поиск задач с использованием JQL с интеллектуальным форматированием и пагинацией

• get_sprint_status — получение подробных отчетов о ходе спринта с метриками

• get_team_workload — анализ рабочей нагрузки и пропускной способности членов команды

• generate_standup_report — автоматическая генерация ежедневных отчетов о стендапах

Возможности управления проектами

• Поддержка нескольких проектов: работа с несколькими проектами путем динамического указания ключей проектов

• Отслеживание прогресса спринта с визуальными индикаторами

• Анализ рабочей нагрузки команды и планирование ресурсов

• Автоматическая генерация ежедневных отчетов о стендапах

• Создание задач с правильной приоритизацией

• Интеллектуальный поиск и фильтрация задач

Надежность

• Автоматический повтор запросов с экспоненциальной задержкой при достижении лимитов скорости (429) и временных ошибках (503)

• Пагинация для больших наборов результатов

• Учет часовых поясов при обработке дат

• Корректная обработка пользовательских статусов и типов задач Jira

Related MCP server: JIRA MCP Server

Требования

• Python 3.8 или выше

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

• MCP-совместимый клиент (например, Claude Desktop)

Быстрая настройка

1. Клонирование и установка:

git clone https://github.com/your-org/mcp-jira.git
cd mcp-jira
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

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

cp .env.example .env
# Edit .env with your values

JIRA_URL=https://your-domain.atlassian.net
JIRA_USERNAME=your.email@domain.com
JIRA_API_TOKEN=your_api_token
PROJECT_KEY=PROJ
DEFAULT_BOARD_ID=123

3. Тестирование сервера:

.venv/bin/python -m mcp_jira

Вы должны увидеть Initializing MCP Jira server... в выводе. Нажмите Ctrl+C для остановки.

Примеры использования

Создание задач

"Create a high priority bug for the login system not working properly"

• Автоматически назначает правильный тип задачи, приоритет и форматирование

Управление спринтом

"What's our current sprint status?"

• Получает подробный отчет о прогрессе с метриками и визуальными индикаторами

Управление командой

"Show me the team workload for john.doe, jane.smith, mike.wilson"

• Анализирует пропускную способность и предоставляет распределение рабочей нагрузки

Ежедневные стендапы

"Generate today's standup report"

• Создает отформатированный отчет с завершенными, текущими и заблокированными задачами

Интеграция с MCP

С Claude Desktop

Файл конфигурации находится по адресу:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Добавьте следующую запись, заменив /path/to/mcp-jira на абсолютный путь, по которому вы клонировали репозиторий:

{
  "mcpServers": {
    "mcp-jira": {
      "command": "/path/to/mcp-jira/.venv/bin/python",
      "args": ["-m", "mcp_jira"]
    }
  }
}

Примечание: Используйте Python-бинарный файл из папки .venv — это гарантирует доступность всех зависимостей. Поле cwd не требуется; сервер разрешает свою конфигурацию, используя абсолютные пути внутри.

Чтобы найти правильный путь, выполните это изнутри директории проекта:

echo "$(pwd)/.venv/bin/python"

Перезапустите Claude Desktop после сохранения конфигурации.

С другими MCP-клиентами

Сервер следует стандартному протоколу MCP и работает с любым MCP-совместимым клиентом.

Конфигурация

Обязательные переменные окружения

• JIRA_URL — URL вашего экземпляра Jira

• JIRA_USERNAME — Ваше имя пользователя/email в Jira

• JIRA_API_TOKEN — Ваш API-токен Jira

• PROJECT_KEY — Ключ проекта по умолчанию для операций (может быть переопределен для каждого запроса)

Дополнительные настройки

• DEFAULT_BOARD_ID — Доска по умолчанию для операций со спринтами (может быть переопределена для каждого запроса)

• STORY_POINTS_FIELD — ID пользовательского поля для Story Points (по умолчанию: customfield_10026)

• DEBUG_MODE — Включение отладочного логирования (по умолчанию: false)

• LOG_LEVEL — Уровень логирования (по умолчанию: INFO)

Получение API-токена Jira

1. Перейдите в Настройки учетной записи Atlassian

2. Нажмите "Create API token"

3. Дайте ему имя и скопируйте токен

4. Используйте свой email в качестве имени пользователя, а токен — в качестве пароля

Архитектура

Эта реализация отдает приоритет простоте и надежности:

• Один файл сервера MCP — все инструменты в одном месте

• Стандартный протокол MCP — использует официальный SDK MCP

• Jira REST API v3 — использует формат Atlassian Document Format (ADF) для описаний

• Богатое форматирование — предоставляет красивые, читабельные отчеты

• Повтор с задержкой — автоматически обрабатывает лимиты скорости и временные ошибки API Jira

• Пагинация — извлекает все результаты для больших наборов задач

• Обработка ошибок — корректная обработка проблем API Jira и пользовательских статусов

• Асинхронная поддержка — быстрые и отзывчивые операции

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

Распространенные проблемы

1. "No active sprint found"

   • Убедитесь, что на вашей доске есть активный спринт

   • Проверьте, правильно ли установлен DEFAULT_BOARD_ID

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

   • Проверьте правильность вашего API-токена

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

3. Ошибки прав доступа

   • Убедитесь, что ваш пользователь Jira имеет соответствующие права доступа к проекту

   • Проверьте, существует ли ключ проекта и есть ли у вас к нему доступ

Режим отладки

Установите DEBUG_MODE=true в вашем файле .env для подробного логирования.

Разработка

1. Сделайте форк репозитория

2. Настройте среду разработки:

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. Запустите тесты:

python -m pytest tests/ -v

4. Отправьте pull request

Лицензия

Лицензия MIT — см. файл LICENSE