MCP Jira Server для Claude Code

Комплексный сервер Model Context Protocol (MCP) для интеграции Jira с Claude Code. Этот сервер предоставляет полный функционал Jira, включая управление задачами, работу со спринтами, комментариями, вложениями и пакетную обработку.

License: MIT TypeScript Node.js

⚠️ Примечание по безопасности: Никогда не сохраняйте свои API-токены в коде! Используйте переменные окружения (например, в ~/.zshrc) или системы управления секретами.

🚀 Функции

📋 Управление задачами (12 инструментов)

create-issue - Создание задач с полной поддержкой полей, включая пользовательские поля и даты
update-issue - Обновление существующих задач с интеллектуальной обработкой полей
get-issue - Получение подробной информации о задаче
search-issues - Расширенный поиск с использованием JQL или упрощенных фильтров с поддержкой дат
transition-issue - Перемещение задач по этапам рабочего процесса
link-issues - Создание связей между задачами (с интеллектуальным сопоставлением типов)
get-link-types - Список доступных типов связей задач
get-fields - Отображение доступных полей для проекта/типа задачи
diagnose-fields - Устранение неполадок конфигурации полей и поиск ID пользовательских полей
create-epic-with-subtasks - Создание эпика с несколькими подзадачами за одну операцию
create-task-for-epic - Создание задачи, связанной с эпиком (оптимизировано для локализованной Jira)

💬 Комментарии и история (3 инструмента)

get-comments - Чтение комментариев к задаче с информацией об авторе и времени
get-history - Просмотр подробной истории изменений с модификациями полей
add-comment - Добавление комментариев с поддержкой формата Atlassian Document Format
batch-comment - Добавление одного и того же комментария к нескольким задачам одновременно

📎 Вложения (2 инструмента)

get-attachments - Список вложений с метаданными (размер, тип, дата загрузки)
upload-attachment - Загрузка файлов с использованием кодировки base64

🏃 Управление спринтами и Agile (4 инструмента)

get-boards - Список доступных досок Jira для Agile-проектов
get-sprints - Просмотр спринтов для доски с индикаторами статуса
move-issue-to-sprint - Перемещение задач между спринтами и бэклогом
create-sprint - Создание новых спринтов с опциональными датами начала/окончания

Ресурсы

jira://projects - Список всех доступных проектов
jira://project/{key} - Получение деталей конкретного проекта
jira://issue/{key} - Получение деталей конкретной задачи
jira://myself - Информация о текущем пользователе
jira://search?jql={query} - Результаты поиска

Промпты

standup-report - Генерация ежедневных отчетов для стендапов
sprint-planning - Помощь в планировании спринтов
bug-triage - Помощь в приоритизации и сортировке багов
release-notes - Генерация примечаний к выпуску на основе завершенных задач
epic-status - Комплексные отчеты о прогрессе по эпикам

Установка

Клонируйте репозиторий:

git clone https://github.com/tom28881/JIRA_MCP.git
cd JIRA_MCP

Установите зависимости:

npm install

Соберите проект:

npm run build

Настройте учетные данные Jira в переменных окружения (например, ~/.zshrc):

Для Jira Cloud:

export JIRA_HOST=https://your-company.atlassian.net
export JIRA_EMAIL=your-email@company.com
export JIRA_API_TOKEN=your-api-token

Для Jira Server/DC 9.12+:

export JIRA_HOST=https://jira.your-company.com
export JIRA_PAT=your-personal-access-token

Для Jira Server/DC (устаревшая версия):

export JIRA_HOST=https://jira.your-company.com
export JIRA_USERNAME=your-username
export JIRA_PASSWORD=your-password

См. docs/AUTH_SETUP.md для получения полного руководства по аутентификации.

Получение учетных данных

Jira Cloud (API Token)

Войдите в настройки учетной записи Atlassian
Нажмите "Create API token"
Дайте ему имя (например, "MCP Server")
Скопируйте токен и добавьте его в конфигурацию оболочки (например, ~/.zshrc) как JIRA_API_TOKEN

Jira Server/DC 9.12+ (Personal Access Token)

Войдите в Jira Server/DC
Перейдите в Профиль → Personal Access Tokens
Нажмите Create token
Установите имя и срок действия (макс. 365 дней)
Скопируйте токен немедленно — его нельзя будет просмотреть снова
Добавьте его в конфигурацию оболочки (например, ~/.zshrc) как JIRA_PAT

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

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

Чтобы использовать этот MCP-сервер с Claude Code, вам нужно настроить его в параметрах MCP.

Вариант 1: Использование переменных окружения (рекомендуется)

Настройте сервер с помощью переменных окружения в конфигурации оболочки (например, ~/.zshrc):

# Add to ~/.zshrc
export JIRA_HOST="https://your-company.atlassian.net"
export JIRA_EMAIL="your-email@company.com"
export JIRA_API_TOKEN="your-api-token"
export JIRA_DEFAULT_PROJECT="PROJ"

# Restart terminal or run: source ~/.zshrc
# Then run Claude Code with the MCP server
claude --mcp "node /absolute/path/to/mcp-jira-server/dist/index.js"

Вариант 2: Добавление в настройки Claude Code

Добавьте сервер в файл настроек Claude Code (~/.claude/settings.json):

{
  "mcpServers": [
    {
      "name": "jira",
      "command": "node",
      "args": ["/absolute/path/to/mcp-jira-server/dist/index.js"],
      "env": {
        "JIRA_HOST": "https://your-company.atlassian.net",
        "JIRA_EMAIL": "your-email@company.com",
        "JIRA_API_TOKEN": "your-api-token",
        "JIRA_DEFAULT_PROJECT": "PROJ"
      }
    }
  ]
}

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

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

Create a new bug in project PROJ with high priority about login issues

Create a story "Implement user authentication" with 5 story points and assign it to john@example.com

Установка дат и оценок времени

Create task "Database backup" with dueDate "next week" and originalEstimate "4h"

Update PROJ-123 with startDate "tomorrow" and dueDate "+14d"

Create issue "Quarterly review" with dueDate "31.3.2025" and originalEstimate "2 days"

Создание эпиков с подзадачами

Create an epic "Database Migration" in project PROJ with subtasks "Backup current data" and "Migrate schema"

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

Create a subtask "Review code" for parent issue PROJ-123

Поддержка чешской локализации Jira

Create issue type "Úkol" in project PROJ

Create task for epic PPC-48 with summary "Database backup"

Поиск задач

Find all open bugs assigned to me

Search for issues in project PROJ with label "urgent" that are not done

Поиск по датам

Search issues due before "next week" in project PROJ

Find issues created after "2024-12-01" and updated after "yesterday"

Search for overdue issues: dueBefore "today" and status != "Done"

Управление задачами

Update PROJ-123 to add story points 8

Transition PROJ-456 to "In Progress"

Link PROJ-123 to PROJ-456 as "blocks"

Примечание: Связи "Эпик-История" используют поле epicLink, а не обычные связи задач:

Update PROJ-456 with epicLink "PROJ-100"  # Links story to epic

Использование промптов

Generate a standup report for john@example.com

Help me plan the sprint for project PROJ

Create release notes for version 2.0 in project PROJ

Расширенная конфигурация

Пользовательские поля

Сервер может работать с любой конфигурацией Jira:

Вариант 1: Автоматическое обнаружение (рекомендуется)

Оставьте ID пользовательских полей не заданными в конфигурации окружения, и сервер автоматически обнаружит их на основе имен полей.

Вариант 2: Ручная конфигурация

Если автоматическое обнаружение не работает, настройте ID пользовательских полей в своем окружении (например, ~/.zshrc):

export JIRA_FIELD_STORY_POINTS=customfield_10001
export JIRA_FIELD_ACCEPTANCE_CRITERIA=customfield_10002
export JIRA_FIELD_EPIC_LINK=customfield_10003

Поиск ID полей

Используйте инструмент diagnose-fields для поиска правильных ID полей для вашего экземпляра Jira:

diagnose-fields project:"PROJ" issueType:"Story"

Автоматическое создание тестовых тикетов

Включите автоматическое создание тестовых тикетов для историй:

AUTO_CREATE_TEST_TICKETS=true

Разработка

Запуск в режиме разработки

npm run dev

Проверка типов

npm run typecheck

Линтинг

npm run lint

Функции

🌍 Поддержка локализации

Автоматическая поддержка локализованных экземпляров Jira (чешский, английский и т.д.)
Имена типов задач могут быть на любом языке (например, "Task", "Úkol", "Aufgabe")
Имена приоритетов поддерживают локализацию (например, "High", "Vysoká", "Hoch")
Специальная поддержка для чешских конфигураций Jira
Работает с любыми языковыми настройками Jira

📅 Управление датами и временем

Гибкие форматы ввода даты:
- ISO: "2024-12-31"
- Европейский: "31.12.2024" или "31/12/2024"
- Относительный: "today", "tomorrow", "next week", "+7d", "+2w", "+1m"
- Чешский: "dnes", "zítra", "příští týden"
Поддержка учета времени:
- Оценки: "2h", "1d 4h", "3 days", "2 hodiny"
- Автоматическое преобразование форматов
Поиск и фильтрация по датам

🔄 Автоматический повтор

Сервер автоматически повторяет неудачные запросы с экспоненциальной задержкой (до 3 попыток).

📦 Надежная обработка ошибок

Обработка пустых ответов для переходов Jira
Подробные сообщения об ошибках с контекстом
Плавная деградация при отсутствии функций

📝 Комплексное логирование

Включите отладочное логирование для просмотра подробной информации:

DEBUG=* claude --mcp "./run.sh"
# or specific to jira-mcp:
DEBUG=jira-mcp claude --mcp "./run.sh"

🔒 Тестирование соединения

Сервер проверяет соединение при запуске и предоставляет четкие сообщения об ошибках в случае сбоя аутентификации.

📄 Формат Atlassian Document Format

Автоматически преобразует обычный текст и Markdown в формат ADF Jira для полей с форматированным текстом.

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

Работа с различными конфигурациями Jira

Этот MCP-сервер разработан для работы с любым экземпляром Jira, независимо от:

Языковых настроек (английский, чешский, немецкий и т.д.)
Конфигураций пользовательских полей
Настроек конкретного проекта

Рекомендации:

Используйте get-fields, чтобы увидеть доступные типы задач на вашем языке
Используйте diagnose-fields, чтобы найти ID пользовательских полей
Создавайте задачи, используя точные имена типов задач из вашей Jira

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

Ошибка аутентификации
- Проверьте правильность вашего API-токена
- Убедитесь, что ваш email совпадает с вашей учетной записью Atlassian
- Проверьте, что URL вашего экземпляра Jira включает https://
Проект не найден
- Проверьте наличие доступа к проекту
- Проверьте правильность ключа проекта (регистрозависимый)
Пользовательские поля не работают
- Используйте инструмент diagnose-fields для поиска правильных ID полей для вашего проекта
- Используйте инструмент get-fields для просмотра всех доступных полей
- ID пользовательских полей обычно начинаются с customfield_
- Некоторые поля могут быть недоступны для определенных типов задач (например, метки в эпиках)
- ID поля Epic Link различается в разных экземплярах Jira
Тип связи не найден
- Используйте инструмент get-link-types для просмотра доступных типов связей
- Типы связей в API Jira регистрозависимы
- Сервер попытается выполнить сопоставление без учета регистра
- Связи "Эпик-История" используют поле epicLink, а не обычные связи задач
Проблемы со связью Эпик-История
- Запустите diagnose-fields для проекта и типа задачи "Story"
- Обновите JIRA_FIELD_EPIC_LINK в конфигурации окружения с правильным ID поля
- Перезапустите терминал или выполните source ~/.zshrc после обновления

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

Установите переменную окружения DEBUG для подробного логирования:

DEBUG=* claude --mcp "./run.sh"
# or
DEBUG=jira-mcp claude --mcp "./run.sh"

Просмотр логов

Логи выводятся в stderr и включают:

Статус соединения
Запросы и ответы API
Детали ошибок с контекстом
Метрики производительности

Участие в разработке

См. CONTRIBUTING.md для руководств по разработке.

Лицензия

Лицензия MIT - подробности см. в файле LICENSE

Поддержка

Для сообщений об ошибках и запросов функций используйте трекер задач GitHub.