atlassian-mcp
by kopyshok
README.md
# atlassian-mcp — Jira и Confluence в чате Open WebUI под своей учёткой
MCP-сервер, через который модель в [Open WebUI](https://github.com/open-webui/open-webui)
читает и правит задачи Jira и страницы Confluence (Server / Data Center).
Главное свойство: **каждое действие выполняется личным токеном того, кто пишет
в чат.** Общей служебной учётки нет ни в каком виде. В истории задачи или
страницы стоит имя пользователя, права Jira и Confluence действуют как обычно:
человек не сделает через чат того, чего не может сделать сам.
Токен пользователь вводит один раз в интерфейсе Open WebUI, в скрытом поле
личных настроек. В переписку он не попадает, модель его не видит.
Внутри — [mcp-atlassian](https://github.com/sooperset/mcp-atlassian) 0.23.1 и
встроенный посредник, который подставляет в каждый запрос токены пользователя.
## Содержание
- [Что умеет](#что-умеет)
- [Как устроено](#как-устроено)
- [Безопасность](#безопасность)
- [Требования](#требования)
- [Установка](#установка)
- [Как пользователь вводит токен](#как-пользователь-вводит-токен)
- [Картинки из чата](#картинки-из-чата)
- [Настройки](#настройки)
- [Если что-то не работает](#если-что-то-не-работает)
- [Проверка](#проверка)
- [Обновление mcp-atlassian](#обновление-mcp-atlassian)
- [Версии](#версии)
- [Лицензия](#лицензия)
## Что умеет
В поставляемой настройке включено 77 инструментов: 75 из mcp-atlassian
и два для загрузки картинок из чата. Набор меняется параметрами `TOOLSETS` и `EXCLUDED_TOOLS`.
**Jira**
| Группа | Что умеет |
|---|---|
| Задачи | Поиск по JQL, чтение задачи со всеми полями, включая дополнительные; создание, в том числе пакетом; изменение любых полей; перенос; назначение исполнителя; история изменений |
| Поля | Поиск поля по названию, допустимые значения полей со списком |
| Комментарии | Добавить, изменить |
| Статусы | Доступные переходы, смена статуса |
| Проекты | Типы задач, поля для создания задачи, версии, компоненты; создание и правка версий |
| Связи | Связать задачи между собой, с эпиком, с внешней ссылкой; убрать связь |
| Agile | Доски, спринты, задачи спринта; создание и правка спринта, перенос задач в спринт и в бэклог |
| Учёт времени | Посмотреть и добавить списание |
| Вложения | Скачать вложения, получить картинки задачи, загрузить картинку из чата |
| Пользователи | Профиль, кого можно назначить исполнителем |
| Наблюдатели | Список, добавить, убрать |
| Даты и SLA | История смены статусов с датами, расчёт SLA |
| Анализ проекта | Иерархия эпиков, связи между проектами |
**Confluence**
| Группа | Что умеет |
|---|---|
| Страницы | Поиск, чтение, создание, правка целиком и по разделу, копирование, перенос, дерево страниц, история и сравнение версий, ограничения доступа |
| Комментарии | Обычные и к фрагменту текста, ответы |
| Вложения | Загрузка, в том числе картинок из чата, скачивание, картинки страницы |
**Не включено:** Jira Service Management, формы ProForma, сведения о разработке
(ветки, коммиты); в Confluence — метки, проверка прав, поиск пользователей,
статистика просмотров, шаблоны (работают только в облаке). **Скрыто удаление**
задач, страниц и вложений.
## Как устроено
```
Пользователь (браузер)
│ чат + форма «Ключи Jira и Confluence» (⚙)
▼
┌──────────────────────── Open WebUI ─────────────────────────┐
│ • личные настройки пользователя: токен Jira, токен Confluence│
│ (хранятся в базе Open WebUI, могут быть зашифрованы) │
│ • подключение MCP к atlassian-mcp, вход «Сессия» │
└──────┬─────────────────────────────────────────▲────────────┘
│ 1. вызов инструмента │ 2. «чья это сессия?
│ + сессия пользователя │ дай его токены»
▼ │
┌──────────────────────── atlassian-mcp ─────────┴────────────┐
│ посредник (server.py) │
│ 3. убирает сессию, подставляет токены пользователя │
│ и адреса Jira/Confluence из своих настроек │
│ mcp-atlassian │
│ 4. проверяет токены, выполняет операцию │
└──────┬───────────────────────────────┬──────────────────────┘
▼ ▼
Jira Server / DC Confluence Server / DC
```
1. Модель вызывает инструмент. Open WebUI отправляет вызов на сервер
и прикладывает сессию пользователя: так работает режим входа «Сессия».
2. Посредник с этой сессией запрашивает у Open WebUI личные настройки
инструмента-формы этого пользователя
(`GET /api/v1/tools/id/<ID формы>/valves/user`). Подделать пользователя нельзя:
кто это, подтверждает сам Open WebUI.
3. Посредник убирает сессию из запроса и добавляет заголовки
`X-Atlassian-Jira-Url`, `X-Atlassian-Jira-Personal-Token` и такие же для
Confluence. Это штатный способ передать mcp-atlassian учётные данные
пользователя на один запрос.
4. mcp-atlassian проверяет токен в Jira или Confluence и выполняет операцию.
**Почему посредник встроен, а не отдельный сервис.** Open WebUI не умеет
подставлять личный секрет пользователя в подключение к MCP-серверу: ключ
подключения один на всех. Поэтому кто-то должен сопоставить сессию и токены.
Посредник встроен в процесс mcp-atlassian: он подменяет `AtlassianMCP.http_app`
и оборачивает приложение. Так получается один контейнер и одна точка входа.
Плата за это — посредник зависит от внутреннего устройства mcp-atlassian,
поэтому версия закреплена, а обновление идёт только через тест (см.
[Обновление mcp-atlassian](#обновление-mcp-atlassian)).
**Форма для токена** — это обычный инструмент Open WebUI без функций
([openwebui_tool.py](openwebui_tool.py)). Open WebUI сам рисует для него форму
личных настроек со скрытыми полями.
## Безопасность
- **Только личные токены.** Сервер не запустится, если в настройках есть общая
учётка (логин, токен, OAuth, сертификат) или отключена проверка личных
токенов (`ALLOW_GLOBAL_CRED_FALLBACK`, `IGNORE_HEADER_AUTH`).
- **Без сессии Open WebUI — отказ.** Запрос без сессии или с чужой
(недействительной) сессией получает ответ 401.
- **Без токена ничего не уходит.** Если пользователь не заполнил форму, модель
получает подсказку, где ввести токен, а запрос в Jira или Confluence
не отправляется.
- **Учётные заголовки от клиента отбрасываются.** Токены и адреса подставляет
только посредник; адреса Jira и Confluence берутся из настроек сервера.
- **Скрытые инструменты нельзя вызвать по имени.** Это обеспечивает
mcp-atlassian: фильтр действует и на список, и на вызов.
- **Хранение токенов.** Токены лежат в базе Open WebUI. Включите встроенное
шифрование (`ENABLE_VALVE_ENCRYPTION=true`, есть с Open WebUI 0.10.0). Тогда
от утечки защищены копия базы, резервная копия, администратор базы
и выгрузка базы из интерфейса.
- **Кому приходится доверять.** Администраторы Open WebUI и сервера — доверенные
лица при любом шифровании. Владелец секретного ключа Open WebUI
(`WEBUI_SECRET_KEY`) может выдать себя за любого пользователя. Администратор
Open WebUI может добавить инструмент со своим кодом, который выполнится
на сервере. Держите эту роль у немногих.
- **Сеть.** Порт сервера наружу не публикуется, к нему ходит только Open WebUI.
Посредник видит сессии пользователей и ничего о них не пишет в журнал.
- **Срок токенов.** Выпускайте личные токены Jira и Confluence с ограниченным
сроком действия.
- **Уязвимость CVE-2026-77244** (обход проверки токенов в mcp-atlassian до
0.22.0) к закреплённой версии 0.23.1 не относится.
## Требования
- Open WebUI с поддержкой MCP и шифрования настроек инструментов, 0.10.0 или
новее. Проверено по исходному коду 0.12.3.
- Jira и Confluence Server / Data Center с личными токенами доступа (Jira 8.14+,
Confluence 7.9+). Облако Atlassian не поддерживается: там другой вид токенов.
- Docker, в той же сети, что и Open WebUI.
- Адреса Jira и Confluence — **по имени сервера, не по IP**: mcp-atlassian
отсекает IP-адреса внутренних сетей.
## Установка
**1. Форма для токенов в Open WebUI.**
«Рабочее пространство → Инструменты → Новый инструмент». Вставить код из
[openwebui_tool.py](openwebui_tool.py), ID инструмента — `atlassian_tokens`.
В «Доступ» дать чтение группе пользователей, которые будут работать с Jira.
В «Панель администратора → Пользователи → Группы → Разрешения» у этой группы
должно быть включено «Разрешить параметры чата» (по умолчанию включено).
**2. Шифрование токенов.** В настройках запуска Open WebUI:
```
ENABLE_VALVE_ENCRYPTION=true
WEBUI_SECRET_KEY=<постоянный ключ>
```
Ключ не менять и хранить отдельно от резервных копий базы. При смене ключа
токены не расшифруются, и пользователям придётся вводить их заново (входы
в Open WebUI тоже сбросятся).
**3. Сервер.** Заполнить адреса в [docker-compose.yml](docker-compose.yml):
`OWUI_URL` — адрес Open WebUI внутри сети Docker, `JIRA_URL`, `CONFLUENCE_URL`.
Указать сеть, в которой работает Open WebUI. Затем:
```
docker compose up -d --build
```
Если сертификат Jira или Confluence выпущен внутренним центром
сертификации, положите корневой сертификат рядом с `Dockerfile` как
`corp-ca.crt` и раскомментируйте две строки в [Dockerfile](Dockerfile).
**4. Подключение в Open WebUI.**
«Панель администратора → Настройки → Интеграции → Внешние серверы инструментов →
Добавить соединение»:
| Поле | Значение |
|---|---|
| Тип | MCP (Streamable HTTP) |
| Адрес | `http://atlassian-mcp:8000/mcp` |
| Вход | **Сессия** |
| Доступ | Группы, которые работают с Jira и Confluence |
**5. Пользователи** создают токены и вставляют их в форму, см. следующий раздел.
## Как пользователь вводит токен
1. Создать токен в Jira: аватар → «Профиль» → раздел Personal Access Tokens →
создать токен со сроком действия. Скопировать: Jira показывает его один раз.
2. То же в Confluence: аватар → «Настройки» → Personal Access Tokens.
3. В чате Open WebUI: «Интеграции → Инструменты» → ⚙ у «Ключи Jira
и Confluence». Вставить оба токена в скрытые поля, сохранить.
Если нужен только один из сервисов, второе поле можно оставить пустым. Тогда
при обращении к этому сервису модель подскажет, где ввести токен.
## Картинки из чата
С версии 1.1.0 MCP передаёт картинки из хранилища Open WebUI в Jira и Confluence.
Песочница и общий диск не нужны; содержимое файла и токены не передаются через модель.
| Инструмент | Параметры |
|---|---|
| `jira_upload_chat_attachment` | `issue_key`, `file_id` |
| `confluence_upload_chat_attachment` | `content_id` (ID страницы), `file_id` |
Модель берёт полный UUID файла из метаданных вложения в сообщении. MCP получает
оригинал с `OWUI_URL/api/v1/files/<file_id>/content` с сессией текущего пользователя.
Open WebUI проверяет право чтения. Затем файл загружается личным токеном Jira
или Confluence. Сессия Open WebUI остаётся только в контексте запроса.
**Загрузка и вставка в текст — два шага.** После подтверждения загрузки возвращаются
имя вложения, его номер, размер, SHA-256 и разметка:
- Jira: `jira_wiki`, затем существующий `jira_update_issue` для изменения описания.
- Confluence: `confluence_storage`, затем `confluence_update_page` с
`content_format="storage"`. Существующую страницу сначала прочитать в storage,
сохранить её текст и добавить разметку изображения без преобразования в Markdown.
Загрузчик текст не меняет: ответ содержит `description_updated=false` или
`page_updated=false`. Если изменение текста не удалось, вложение уже может быть
на месте: проверить его, затем повторить только изменение текста.
Ограничения:
- PNG, JPEG, GIF и WebP, максимум 10 МиБ. Формат определяется по сигнатуре,
содержимое не перекодируется. В Jira/Confluence может действовать меньший лимит.
- Нужен существующий файл Open WebUI и полный UUID. Путь `/mnt/uploads/...`, URL
и Base64 не принимаются. Картинку, созданную только в песочнице, сначала нужно
сохранить как вложение Open WebUI.
- При вставке из буфера требуется сохранение оригинала в хранилище Open WebUI,
например уже используемым фильтром `paste_images_to_sandbox.py`. Если метаданных
файла нет, попробовать обычное прикрепление. Не угадывать UUID из имени `pasted_...`.
- Имя вложения: `chat-<полный UUID>.<формат>`. Разные файлы с исходным именем
`image.png` не сталкиваются. Повторный вызов для того же файла может создать
дубль в Jira; Confluence Server/DC отклоняет совпадающее имя. Проверять уже
имеющееся вложение перед повтором; автоматического удаления или замены нет.
- Скачивание ограничено 30 секундами и не следует перенаправлениям. Загрузка
использует тайм-аут клиента Atlassian; автоматические повторы загрузки отключены.
- Режим чтения и исключение инструментов действуют и на новые команды.
Пример запроса: «Приложи эту картинку к задаче TEST-1 и вставь в конец описания,
сохранив прежний текст». Для Confluence указать согласованную тестовую страницу.
### Обновление с 1.0.0
1. Обновить файлы, включая `chat_attachments.py`, и пересобрать сервер:
`docker compose up -d --build`. Адреса и личные токены остаются прежними.
2. Обновить список инструментов подключения MCP в Open WebUI. Должны появиться
две команды из таблицы. Группы `jira_attachments` и `confluence_attachments`
уже включены в поставляемый пример настроек.
3. Прикрепить картинку в чате. В тестовой задаче и странице проверить загрузку,
отображение внутри текста, открытие оригинала и сохранность прежнего текста.
На рабочей установке эта проверка обязательна: локально сервисы заменены заглушками.
## Настройки
| Параметр | Значение |
|---|---|
| `OWUI_URL` | Адрес Open WebUI внутри сети Docker, например `http://open-webui:8080`. Обязателен |
| `OWUI_TOOL_ID` | ID инструмента-формы в Open WebUI, по умолчанию `atlassian_tokens` |
| `JIRA_URL`, `CONFLUENCE_URL` | Адреса серверов, по имени, не по IP. Можно указать только один |
| `TOOLSETS` | Группы инструментов mcp-atlassian через запятую. Поставляемое значение — в [docker-compose.yml](docker-compose.yml) |
| `EXCLUDED_TOOLS` | Скрытые инструменты через запятую. Сейчас скрыто удаление задач, страниц и вложений. При опечатке в названии сервер не запустится |
| `READ_ONLY_MODE` | `true` — только чтение, удобно на время пробы |
| `MCP_ALLOWED_URL_DOMAINS` | Задаётся автоматически по `JIRA_URL` и `CONFLUENCE_URL` |
Остальные параметры mcp-atlassian (таймауты, прокси, фильтр проектов
`JIRA_PROJECTS_FILTER`, фильтр пространств `CONFLUENCE_SPACES_FILTER`) работают
как описано в его документации. Учётные параметры запрещены.
## Если что-то не работает
| Что видно | Что проверить |
|---|---|
| Контейнер сразу останавливается, в журнале «Ошибка настройки: …» | Текст ошибки называет параметр: общая учётка в настройках, IP вместо имени сервера, неизвестный инструмент в `EXCLUDED_TOOLS`, не задан `OWUI_URL` |
| Open WebUI не может подключиться, ответ 401 | В подключении выбран вход «Сессия» |
| Модель отвечает «Личный токен … не задан» | Пользователь не заполнил форму; `OWUI_TOOL_ID` совпадает с ID инструмента-формы |
| Ответ «Open WebUI недоступен» или «Open WebUI ответил …» | `OWUI_URL` и общая сеть Docker |
| Jira или Confluence отвечает ошибкой авторизации | Токен истёк или отозван: создать новый и вставить в форму |
| Ошибка сертификата | Внутренний корневой сертификат, см. шаг 3 установки |
| Нет нужного инструмента | `TOOLSETS` и `EXCLUDED_TOOLS` |
## Проверка
[test_e2e.py](test_e2e.py) поднимает заглушки Open WebUI, Jira и Confluence,
запускает сервер и проверяет:
- инструменты видны, скрытый инструмент отсутствует и не вызывается по имени;
- чтение задачи со всеми полями и запись поля идут токеном Jira пользователя;
- чтение страницы идёт токеном Confluence;
- без токена приходит подсказка, запросов в Jira нет;
- без сессии и с чужой сессией — отказ.
В образе, то есть в той же среде, что и на сервере:
```
docker build -t atlassian-mcp:1.1.0 .
docker run --rm -v "$PWD:/src:ro" -w /src -e STUB_HOST=stub.test \
--add-host stub.test:127.0.0.1 atlassian-mcp:1.1.0 python test_e2e.py
```
На Windows без Docker:
```
pip install -r requirements.txt
python test_e2e.py
python -m unittest test_chat_attachments -v
python test_chat_e2e.py
```
Успех — строка `OK: все проверки прошли`.
Для картинок unittest должен завершиться `OK`, а `test_chat_e2e.py` — тремя
строками `OK: chat attachments`: обычный режим, режим чтения, исключённые инструменты.
В образе использовать ту же команду `docker run`, заменив последнюю команду Python.
Все проверки работают на заглушках и не обращаются к корпоративным сервисам.
## Обновление mcp-atlassian
Посредник опирается на внутреннее устройство mcp-atlassian, поэтому версия
закреплена вместе со всеми зависимостями в [requirements.txt](requirements.txt).
Обновлять только так:
1. Поменять версию и пересобрать список зависимостей:
`uv pip compile --no-annotate --no-header --python-platform linux --python-version 3.12 requirements.in -o requirements.txt`,
где в `requirements.in` одна строка `mcp-atlassian==<версия>`.
2. Собрать образ и прогнать тест в нём (раздел [Проверка](#проверка)).
3. Если тест прошёл — выложить новую версию сервера.
## Версии
Номер версии — `основная.дополнительная.исправление`:
- **основная** меняется, когда нужно что-то менять у себя: настройки сервера,
форму в Open WebUI, подключение;
- **дополнительная** — новые возможности без изменений у себя;
- **исправление** — исправления.
История — в [CHANGELOG.md](CHANGELOG.md).
## Лицензия
MIT, см. [LICENSE](LICENSE). mcp-atlassian распространяется под лицензией MIT.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues