МКП Atlassian

Сервер Model Context Protocol (MCP) для продуктов Atlassian (Confluence и Jira). Эта интеграция поддерживает как Confluence & Jira Cloud, так и развертывания Server/Data Center.

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

Попросите вашего помощника на основе искусственного интеллекта:

• 📝 Автоматические обновления Jira — «Обновляйте Jira из наших заметок о встречах»

• 🔍 Поиск Confluence на базе искусственного интеллекта — «Найдите наше руководство по OKR в Confluence и обобщите его»

• 🐛 Фильтрация проблем Smart Jira — «Покажи мне срочные ошибки в проекте PROJ за прошлую неделю»

• 📄 Создание и управление контентом — «Создание технического дизайн-документа для функции XYZ»

Демонстрация функций

https://github.com/user-attachments/assets/35303504-14c6-4ae4-913b-7c25ea511c3e

https://github.com/user-attachments/assets/7fe9c488-ad0c-4876-9b54-120b666bb785

Совместимость

Related MCP server: MCP Atlassian

Краткое руководство пользователя

🔐 1. Настройка аутентификации

MCP Atlassian поддерживает три метода аутентификации:

A. Аутентификация с помощью API-токена (облако)

1. Перейдите по ссылке https://id.atlassian.com/manage-profile/security/api-tokens

2. Нажмите «Создать токен API» , дайте ему имя.

3. Немедленно скопируйте токен

B. Персональный токен доступа (сервер/центр обработки данных)

1. Перейдите в свой профиль (аватар) → Профиль → Персональные токены доступа

2. Нажмите «Создать токен» , дайте ему имя и установите срок действия.

3. Немедленно скопируйте токен

C. Аутентификация OAuth 2.0 (Облако)

1. Перейти в консоль разработчика Atlassian

2. Создайте приложение «Интеграция OAuth 2.0 (3LO)»

3. Настройка разрешений (областей действия) для Jira/Confluence

4. Установить URL обратного вызова (например, http://localhost:8080/callback )

5. Запустите мастер настройки:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

6. Следуйте подсказкам для Client ID , Secret , URI и Scope

7. Полная авторизация браузера

8. Добавьте полученные учетные данные в .env или конфигурацию IDE:

   • ATLASSIAN_OAUTH_CLOUD_ID (из мастера)

   • ATLASSIAN_OAUTH_CLIENT_ID

   • ATLASSIAN_OAUTH_CLIENT_SECRET

   • ATLASSIAN_OAUTH_REDIRECT_URI

   • ATLASSIAN_OAUTH_SCOPE

[!ВАЖНО] Включите offline_access в область действия для постоянной аутентификации (например, read:jira-work write:jira-work offline_access )

📦 2. Установка

MCP Atlassian распространяется как образ Docker. Это рекомендуемый способ запуска сервера, особенно для интеграции IDE. Убедитесь, что у вас установлен Docker.

# Pull Pre-built Image
docker pull ghcr.io/sooperset/mcp-atlassian:latest

🛠️ Интеграция с IDE

MCP Atlassian предназначен для использования с помощниками на базе искусственного интеллекта посредством интеграции с IDE.

[!СОВЕТ] Для Claude Desktop : найдите и отредактируйте файл конфигурации напрямую:

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

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

• Linux : ~/.config/Claude/claude_desktop_config.json

Для курсора : Откройте Настройки → MCP → + Добавить новый глобальный сервер MCP

⚙️ Методы настройки

Существует два основных подхода к настройке контейнера Docker:

1. Прямая передача переменных (показано в примерах ниже)

2. Использование файла среды с флагом --env-file (показано в сворачиваемых разделах)

[!ПРИМЕЧАНИЕ] К общим переменным среды относятся:

• CONFLUENCE_SPACES_FILTER : Фильтр по пробельным клавишам (например, «DEV,TEAM,DOC»)

• JIRA_PROJECTS_FILTER : Фильтр по ключам проекта (например, «PROJ,DEV,SUPPORT»)

• READ_ONLY_MODE : установите значение «true», чтобы отключить операции записи.

• MCP_VERBOSE : установите значение «true» для более подробного протоколирования.

• ENABLED_TOOLS : разделенный запятыми список названий инструментов, которые необходимо включить (например, «confluence_search,jira_get_issue»).

Все доступные параметры см. в файле .env.example .

📝 Примеры конфигурации

Метод 1 (передача переменных напрямую):

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_confluence_api_token",
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_jira_api_token"
      }
    }
  }
}

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--env-file",
        "/path/to/your/mcp-atlassian.env",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ]
    }
  }
}

Для развертываний на сервере/в центре обработки данных используйте прямую передачу переменных:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "-e", "CONFLUENCE_SSL_VERIFY",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "-e", "JIRA_SSL_VERIFY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_confluence_pat",
        "CONFLUENCE_SSL_VERIFY": "false",
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_jira_pat",
        "JIRA_SSL_VERIFY": "false"
      }
    }
  }
}

[!ПРИМЕЧАНИЕ] Устанавливайте CONFLUENCE_SSL_VERIFY и JIRA_SSL_VERIFY на «false», только если у вас есть самоподписанные сертификаты.

В этом примере показано, как настроить mcp-atlassian в вашей IDE (например, Cursor или Claude Desktop) при использовании OAuth 2.0 для Atlassian Cloud. Убедитесь, что вы сначала завершили работу мастера настройки OAuth .

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v", "<path_to_your_home>/.mcp-atlassian:/home/app/.mcp-atlassian",
        "-e", "JIRA_URL",
        "-e", "CONFLUENCE_URL",
        "-e", "ATLASSIAN_OAUTH_CLIENT_ID",
        "-e", "ATLASSIAN_OAUTH_CLIENT_SECRET",
        "-e", "ATLASSIAN_OAUTH_REDIRECT_URI",
        "-e", "ATLASSIAN_OAUTH_SCOPE",
        "-e", "ATLASSIAN_OAUTH_CLOUD_ID",
        "ghcr.io/sooperset/mcp-atlassian:latest",
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "ATLASSIAN_OAUTH_CLIENT_ID": "YOUR_OAUTH_APP_CLIENT_ID",
        "ATLASSIAN_OAUTH_CLIENT_SECRET": "YOUR_OAUTH_APP_CLIENT_SECRET",
        "ATLASSIAN_OAUTH_REDIRECT_URI": "http://localhost:8080/callback",
        "ATLASSIAN_OAUTH_SCOPE": "read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access",
        "ATLASSIAN_OAUTH_CLOUD_ID": "YOUR_CLOUD_ID_FROM_SETUP_WIZARD"
      }
    }
  }
}

[!ПРИМЕЧАНИЕ]

• ATLASSIAN_OAUTH_CLOUD_ID получается из выходных данных мастера --oauth-setup .

• Другие переменные ATLASSIAN_OAUTH_* — это те, которые вы настроили для своего приложения OAuth в консоли разработчика Atlassian (и использовали в качестве входных данных для мастера настройки).

• JIRA_URL и CONFLUENCE_URL для ваших облачных экземпляров по-прежнему обязательны.

MCP Atlassian поддерживает маршрутизацию запросов API через стандартные HTTP/HTTPS/SOCKS прокси. Настройте с помощью переменных среды:

• Поддерживает стандартные HTTP_PROXY , HTTPS_PROXY , NO_PROXY , SOCKS_PROXY .

• Доступны переопределения для конкретных служб (например, JIRA_HTTPS_PROXY , CONFLUENCE_NO_PROXY ).

• Специфичные для сервиса переменные переопределяют глобальные переменные для этого сервиса.

Добавьте соответствующие переменные прокси в разделы args (используя -e ) и env вашей конфигурации MCP:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "... existing Confluence/Jira vars",
        "-e", "HTTP_PROXY",
        "-e", "HTTPS_PROXY",
        "-e", "NO_PROXY",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "... existing Confluence/Jira vars": "...",
        "HTTP_PROXY": "http://proxy.internal:8080",
        "HTTPS_PROXY": "http://proxy.internal:8080",
        "NO_PROXY": "localhost,.your-company.com"
      }
    }
  }
}

Учетные данные в URL-адресах прокси маскируются в журналах. Если вы установите NO_PROXY , он будет учитываться для запросов к соответствующим хостам.

Только для Confluence Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_USERNAME",
        "-e", "CONFLUENCE_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://your-company.atlassian.net/wiki",
        "CONFLUENCE_USERNAME": "your.email@company.com",
        "CONFLUENCE_API_TOKEN": "your_api_token"
      }
    }
  }
}

Для Confluence Server/DC используйте:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "CONFLUENCE_URL",
        "-e", "CONFLUENCE_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "CONFLUENCE_URL": "https://confluence.your-company.com",
        "CONFLUENCE_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

Только для Jira Cloud:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_USERNAME",
        "-e", "JIRA_API_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://your-company.atlassian.net",
        "JIRA_USERNAME": "your.email@company.com",
        "JIRA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Для Jira Server/DC используйте:

{
  "mcpServers": {
    "mcp-atlassian": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "JIRA_URL",
        "-e", "JIRA_PERSONAL_TOKEN",
        "ghcr.io/sooperset/mcp-atlassian:latest"
      ],
      "env": {
        "JIRA_URL": "https://jira.your-company.com",
        "JIRA_PERSONAL_TOKEN": "your_personal_token"
      }
    }
  }
}

👥 Конфигурация HTTP-транспорта

Вместо использования stdio вы можете запустить сервер как постоянную службу HTTP, используя один из следующих способов:

• Транспорт sse (события, отправленные сервером) в конечной точке /sse

• streamable-http -транспортирование в конечной точке /mcp

Оба типа транспорта поддерживают однопользовательскую и многопользовательскую аутентификацию:

Варианты аутентификации:

• Однопользовательский режим : использование аутентификации на уровне сервера, настроенной с помощью переменных среды.

• Многопользовательский режим : каждый пользователь обеспечивает собственную аутентификацию:

  • Облако: токены на предъявителя OAuth 2.0

  • Сервер/Центр обработки данных: Персональные токены доступа (PAT)

1. Запустите сервер с выбранным вами транспортом:

   # For SSE transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport sse --port 9000 -vv
   
   # OR for streamable-http transport
   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

2. Настройте свою IDE (пример для одного пользователя):

   Пример транспорта SSE:

   {
     "mcpServers": {
       "mcp-atlassian-http": {
         "url": "http://localhost:9000/sse"
       }
     }
   }

   Пример потокового HTTP-транспорта:

   {
     "mcpServers": {
       "mcp-atlassian-service": {
         "url": "http://localhost:9000/mcp"
       }
     }
   }

Вот полный пример настройки многопользовательской аутентификации с использованием потокового HTTP-транспорта:

1. Сначала запустите мастер настройки OAuth, чтобы настроить учетные данные OAuth сервера:

   docker run --rm -i \
     -p 8080:8080 \
     -v "${HOME}/.mcp-atlassian:/home/app/.mcp-atlassian" \
     ghcr.io/sooperset/mcp-atlassian:latest --oauth-setup -v

2. Запустите сервер с потоковым HTTP-транспортом:

   docker run --rm -p 9000:9000 \
     --env-file /path/to/your/.env \
     ghcr.io/sooperset/mcp-atlassian:latest \
     --transport streamable-http --port 9000 -vv

3. Настройте параметры MCP вашей IDE:

Выберите подходящий метод авторизации для вашего развертывания Atlassian:

• Облако (OAuth 2.0): используйте этот вариант, если ваша организация работает в Atlassian Cloud и у вас есть токен доступа OAuth для каждого пользователя.

• Сервер/центр обработки данных (PAT): используйте этот вариант, если вы используете Atlassian Server или Data Center и у каждого пользователя есть персональный токен доступа (PAT).

Пример облака (OAuth 2.0):

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Bearer <USER_OAUTH_ACCESS_TOKEN>"
      }
    }
  }
}

Пример сервера/центра обработки данных (PAT):

{
  "mcpServers": {
    "mcp-atlassian-service": {
      "url": "http://localhost:9000/mcp",
      "headers": {
        "Authorization": "Token <USER_PERSONAL_ACCESS_TOKEN>"
      }
    }
  }
}

4. Необходимые переменные среды в .env :

   JIRA_URL=https://your-company.atlassian.net
   CONFLUENCE_URL=https://your-company.atlassian.net/wiki
   ATLASSIAN_OAUTH_CLIENT_ID=your_oauth_app_client_id
   ATLASSIAN_OAUTH_CLIENT_SECRET=your_oauth_app_client_secret
   ATLASSIAN_OAUTH_REDIRECT_URI=http://localhost:8080/callback
   ATLASSIAN_OAUTH_SCOPE=read:jira-work write:jira-work read:confluence-content.all write:confluence-content offline_access
   ATLASSIAN_OAUTH_CLOUD_ID=your_cloud_id_from_setup_wizard

[!ПРИМЕЧАНИЕ]

• Сервер должен иметь собственную настроенную резервную аутентификацию (например, через переменные среды для токена API, PAT или собственную настройку OAuth с помощью --oauth-setup). Это используется, если запрос не включает аутентификацию, специфичную для пользователя.

• OAuth : каждому пользователю необходим собственный токен доступа OAuth из вашего приложения Atlassian OAuth.

• PAT : Каждый пользователь предоставляет свой собственный персональный токен доступа.

• Сервер будет использовать токен пользователя для вызовов API, если он предоставлен, и перейдет к аутентификации сервера, если нет.

• Токены пользователей должны иметь соответствующие области действия для необходимых им операций.

Инструменты

Ключевые инструменты

Инструменты Jira

• jira_get_issue : Получить сведения о конкретной проблеме

• jira_search : Поиск проблем с использованием JQL

• jira_create_issue : Создать новую задачу

• jira_update_issue : Обновить существующую задачу

• jira_transition_issue : Перевести задачу в новый статус

• jira_add_comment : Добавить комментарий к задаче

Инструменты слияния

• confluence_search : Поиск контента Confluence с использованием CQL

• confluence_get_page : Получить содержимое определенной страницы

• confluence_create_page : Создать новую страницу

• confluence_update_page : Обновить существующую страницу

*Инструмент доступен только в Jira Cloud

Фильтрация инструментов и контроль доступа

Сервер предоставляет два способа управления доступом к инструментам:

1. Фильтрация инструментов : используйте флаг --enabled-tools или переменную среды ENABLED_TOOLS , чтобы указать, какие инструменты должны быть доступны:

   # Via environment variable
   ENABLED_TOOLS="confluence_search,jira_get_issue,jira_search"
   
   # Or via command line flag
   docker run ... --enabled-tools "confluence_search,jira_get_issue,jira_search" ...

2. Управление чтением/записью : инструменты классифицируются как операции чтения или записи. Когда включен READ_ONLY_MODE , доступны только операции чтения независимо от настройки ENABLED_TOOLS .

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

Общие проблемы

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

  • Для облака: проверьте свои токены API (не пароль учетной записи)

  • Для сервера/центра обработки данных: убедитесь, что ваш персональный токен доступа действителен и не просрочен.

  • Для старых серверов Confluence: некоторые старые версии требуют базовой аутентификации с CONFLUENCE_USERNAME и CONFLUENCE_API_TOKEN (где token — ваш пароль)

• Проблемы с сертификатом SSL : если вы используете сервер/центр обработки данных и столкнулись с ошибками SSL, установите CONFLUENCE_SSL_VERIFY=false или JIRA_SSL_VERIFY=false

• Ошибки прав доступа : убедитесь, что у вашей учетной записи Atlassian достаточно прав для доступа к пространствам/проектам.

Инструменты отладки

# Using MCP Inspector for testing
npx @modelcontextprotocol/inspector uvx mcp-atlassian ...

# For local development version
npx @modelcontextprotocol/inspector uv --directory /path/to/your/mcp-atlassian run mcp-atlassian ...

# View logs
# macOS
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log
# Windows
type %APPDATA%\Claude\logs\mcp*.log | more

Безопасность

• Никогда не делитесь токенами API

• Сохраняйте файлы .env в безопасности и конфиденциальности

• Ознакомьтесь с рекомендациями SECURITY.md.

Внося вклад

Мы приветствуем вклад в MCP Atlassian! Если вы хотите внести свой вклад:

1. Подробные инструкции по настройке разработки см. в нашем руководстве CONTRIBUTING.md .

2. Внесите изменения и отправьте запрос на извлечение.

Мы используем предварительные проверки качества кода и следуем семантическому версионированию для релизов.

Лицензия

Лицензия MIT - см. файл LICENSE . Это не официальный продукт Atlassian.