atlassian-mcp

Сервер Model Context Protocol (MCP) для самостоятельно размещённого Jira (Server / Data Center) и самостоятельно размещённого Bitbucket (Server / Data Center). Предоставляет инструменты для рабочих процессов на естественном языке вокруг задач, пул-реквестов, веток обсуждений и git-контекста.

Примечание: Этот сервер поддерживает только самостоятельно размещённые экземпляры. Jira Cloud и Bitbucket Cloud используют другие API и не поддерживаются.

Tools

Workflow

Git

Jira

Bitbucket

Natural language examples

• "над чем я работаю?" → get_dev_context

• "создай ветку для FOO-123" → start_work

• "отправь это / объедини и закрой задачу" → complete_work

• "покажи мои PR, ожидающие ревью" → bitbucket_search with mine=true

• "перечисли открытые PR для этого репозитория из feature/ABC-123" → bitbucket_search with fromBranch

• "дай мне полный обзор PR 42" → bitbucket_get_pr

• "открой PR из моей текущей ветки в master" → bitbucket_mutate with create

• "одобрить / объединить / отклонить PR 42" → bitbucket_mutate with action

• "ответить на комментарий 123 в PR 42" → bitbucket_comment with commentId=123

• "разрешить этот блокировщик в PR 42" → bitbucket_comment with action=update, severity=BLOCKER, state=RESOLVED

• "перечисли задачи чек-листа PR" → bitbucket_pr_tasks with action=list

• "найди ошибки, назначенные на меня в проекте PAY" → jira_search with mine=true, issueType=Bug

• "что в текущем спринте?" → jira_search with resource=board_overview

• "перемести FOO-123 в In Progress" → jira_mutate with transitionName="In Progress"

• "запиши 2 часа на FOO-123" → jira_mutate with worklog

• "создай версию 9.1.0 в PAY" → jira_version with action=create, projectKey=PAY, name=9.1.0

• "перечисли релизы для PAY" → jira_search with resource=versions, project=PAY

• "выпусти версию 12345" → jira_version with action=release, id=12345

• "установи версию исправления 9.1.0 на FOO-123" → jira_mutate with update.fixVersion=9.1.0

• "создай задачу под эпиком FOO-100" → jira_mutate with create.issueType=Task, create.parent=FOO-100 (автоматически определяет Epic и устанавливает Epic Link)

• "перемести FOO-123 под эпик FOO-100" → jira_mutate with update.epicLink=FOO-100

• "создай эпик" → jira_mutate with create.issueType=Epic (Epic Name по умолчанию равен сводке)

• "установи story points в 5" → jira_mutate with update.customFields={"Story Points": 5} — значения простые (метка опции, имя пользователя, дата, массив меток); сервер оборачивает их в соответствии со схемой поля

• "что я могу установить в этой задаче / в эпике?" → jira_search resource=fields with issueKey=FOO-123 (экран редактирования) или project=FOO+issueType=Epic (экран создания): обязательные и необязательные поля, формы значений, допустимые значения

Related MCP server: Bitbucket Server MCP

Setup

1. Create a config file

Создайте ~/.atlassian-mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/stubbedev/atlassian-mcp/master/atlassian-mcp.schema.json",
  "jira": {
    "url": "https://jira.example.com",
    "token": "your-jira-personal-access-token"
  },
  "bitbucket": {
    "url": "https://bitbucket.example.com",
    "token": "your-bitbucket-personal-access-token"
  }
}

Поле $schema необязательно, но включает автодополнение и проверку в редакторе.

• projectKey означает код проекта:

  • Пример Jira: PAY в задаче PAY-123

  • Пример Bitbucket: проект ENG в пути репозитория ENG/payments-service

• Также можно использовать эргономичные псевдонимы:

  • Jira: project (псевдоним projectKey)

  • Bitbucket: project и repo (псевдонимы projectKey и repoSlug)

• Для инструментов Bitbucket projectKey и repoSlug обычно автоматически определяются из вашего локального удалённого репозитория origin.

• bitbucket_create_pull_request также автоматически определяет fromBranch из вашей текущей ветки и возвращает существующий открытый PR, если он уже есть для этой ветки.

• Вызовы Jira, ограниченные проектом, принимают projectKey и работают лучше всего, когда он указан.

• Если projectKey опущен при создании задачи Jira или поиске типа, сервер пытается определить его из ключа задачи в текущей ветке, при отсутствии — автоматически выбирает, если виден только один проект, иначе возвращает нумерованный список проектов для выбора.

В качестве альтернативы используйте переменные окружения (или файл .env в этом каталоге):

JIRA_URL=https://jira.example.com
JIRA_ACCESS_TOKEN=your-jira-personal-access-token
BITBUCKET_URL=https://bitbucket.example.com
BITBUCKET_ACCESS_TOKEN=your-bitbucket-personal-access-token

Конфигурация разрешается в следующем порядке: аргумент CLI --config <path> → переменная окружения ATLASSIAN_MCP_CONFIG → ~/.atlassian-mcp.json → $XDG_CONFIG_HOME/atlassian-mcp/config.json (по умолчанию ~/.config/atlassian-mcp/config.json) → .atlassian-mcp.json в текущем каталоге → переменные окружения.

2. Connect to your AI tool

Не требуется клонирование или сборка — просто укажите вашему инструменту на npx @stubbedev/atlassian-mcp@latest, и он установится и запустится автоматически.

Примечание: --prefer-online может нарушить запуск MCP в некоторых клиентах. Держите команду простой и используйте шаги обновления ниже, когда захотите обновить.

Claude Code

claude mcp add atlassian -- npx -y @stubbedev/atlassian-mcp@latest --config ~/.atlassian-mcp.json

Cursor

Добавьте в ~/.cursor/mcp.json (глобально) или .cursor/mcp.json (только для проекта):

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Windsurf

Добавьте в ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "atlassian": {
      "command": "npx",
      "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/Users/you/.atlassian-mcp.json"]
    }
  }
}

Zed

Добавьте в ~/.config/zed/settings.json:

{
  "context_servers": {
    "atlassian": {
      "command": {
        "path": "npx",
        "args": ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
      }
    }
  }
}

OpenCode

Добавьте в opencode.json в корне вашего проекта (или ~/.config/opencode/opencode.json для глобального):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atlassian": {
      "type": "local",
      "command": ["npx", "-y", "@stubbedev/atlassian-mcp@latest", "--config", "/home/you/.atlassian-mcp.json"]
    }
  }
}

Codex CLI

Добавьте в ~/.codex/config.yaml:

mcpServers:
  atlassian:
    command: npx
    args:
      - -y
      - @stubbedev/atlassian-mcp@latest
      - --config
      - /home/you/.atlassian-mcp.json

Any other MCP-compatible tool

Большинство инструментов, поддерживающих MCP, принимают тот же формат JSON. Используйте npx в качестве команды с ["-y", "@stubbedev/atlassian-mcp@latest", "--config", "/path/to/config.json"] в качестве аргументов.

Updating existing installs

Если ваш MCP-клиент уже настроен и вы хотите получить новейшую версию пакета:

npx clear-npx-cache

Затем перезапустите MCP-клиент.

Установка без npm

Сервер — это один статический Go-бинарник. Путь npx выше скачивает готовый бинарник для вашей платформы при первом запуске; следующие варианты полностью минуют Node:

# Go toolchain — installs to $GOBIN / $GOPATH/bin
go install github.com/stubbedev/atlassian-mcp@latest

# Nix flake
nix run github:stubbedev/atlassian-mcp -- --config ~/.atlassian-mcp.json

Затем укажите в MCP-клиенте command на полученный бинарник atlassian-mcp вместо npx. На этих путях ffmpeg/ffprobe должны быть доступны через PATH (или задайте ATLASSIAN_MCP_FFMPEG_PATH / ATLASSIAN_MCP_FFPROBE_PATH); npm-обёртка подключает их автоматически.

Запуск как HTTP-сервера (общий / за обратным прокси)

По умолчанию сервер использует протокол MCP через stdio (один процесс на клиента, запускается вашим редактором). Вместо этого он может работать как долгоживущий Streamable HTTP-сервер, общий для многих клиентов — удобно за обратным реверс-прокси:

atlassian-mcp --http                 # binds 127.0.0.1:7337
atlassian-mcp --http 127.0.0.1:9000  # custom address
ATLASSIAN_MCP_HTTP=1 atlassian-mcp   # same, via env

• Единая конечная точка POST /mcp (JSON-RPC), а также опциональный SSE-поток GET /mcp, передающий запросы от сервера к клиентам (roots, elicitation/list). Сервер осознанный: initialize создаёт сессию и возвращает заголовок Mcp-Session-Id, который клиент обязан повторять в каждом последующем запросе и в SSE-потоке. Запросы с отсутствующим/неизвестным/просроченным id сессии получают HTTP 404, чтобы клиент переинициализировался (стандартное поведение MCP-клиента). Каждый подключённый клиент/worktree — изолированная сессия.

Аутентификация: на loopback-привязке токен не требуется. Привязка к не-loopback-адресу требует ATLASSIAN_MCP_HTTP_TOKEN (клиенты передают как Authorization: Bearer …); иначе сервер откажет запуск. Завершайте TLS-терминирование на своём прокси. GETZ /health — неаутентифицированный liveness-пробник (возвращает ok) для прокси/балансеров. Простаивающие сессии вытесняются через 1 час.

Контекст репозитория берётся от клиента, а не из рабочей директории сервера. Инструменты, которым нужен репозиторий (инструменты git_*, get_dev_context, start_work, complete_work и автоопределение Bitbucket/репозитория) разрешают его в следующем порядке: явный аргумент repoPath → корневой путь, заданный через заголовок запроса (см. ниже) → корневые пути MCP клиента (сервер запрашивает через root/list, кэширует по сессиям и обновляет по notifications/roots/list_changed) → текущая рабочая директория процесса (только stdio). Значит, один общий HTTP-сервер обслуживает много worktree: свой клиентский workspace движет его вызовами. Когда сессия показывает несколько корней (несколько worktree), инструмент без repoPath использует первый git-репозиторий из корня; передайте repoPath (абсолютный путь или имя worktree/базовое имя, совпадающее с одним из корней) для конкретного worktree. Для Bitbucket передача projectKey+repoSlug полностью пропускает определение репозитория. Репозитории должны быть доступны на хосте сервера (git-инструменты запускают git локально).

Закрепление корня через заголовок запроса (HTTP). Обратный прокси или хуks, который уже знает worktree, может передать его серверу напрямую, минуя круг roots/list (и работает даже когда клиент никогда не анонсировал capability roots). Передайте file:// URI или абсолютный путь (через запятую для нескольких; первый git-репозиторий побеждает):

X-Mcp-Root: file:///srv/myrepo
X-Mcp-Roots: /srv/a, /srv/b

Принятые заголовки: X-Mcp-Roots, X-Mcp-Root, Mcp-Roots, Mcp-Root. Значение заголовка — авторитетное; оно имеет приоритет над roots/list и переживает list_changed.

Конфигурация клиента для уже запущенного HTTP-сервера (пример Claude Code):

claude mcp add --transport http atlassian http://127.0.0.1:7337/mcp

Конвейер декодирования вложений

Инструменты для вложений (jira_get_attachment, bitbucket_get_attachment) декодируют бинарные вложения в читаемые моделью содержимые до возврата:

Автосохранённые файлы периодически удаляются по времени жизни (TTL) и квоте на общий размер — см. переопределения среды ниже.

Внешние инструменты (опционально)

Изображения и PDF-текст — чисто Go-декодирование, ничего дополнительно не нужно. Два конвейера без чисто-Go реализации требуют запуска внешних бинарников:

• ffmpeg + ffprobe — видеокадры и анимированные изображения. npm-обёртка включает ffmpeg-static / ffprobe-static и подставляет их пути, так что для установки через npx не требуется нулевая конфигурация. При установке через go install / Nix, установите ffmpeg (он предоставляет ffprobe) или задайте переменные окружения ниже.

• pdftoppm (poppler) или mutool (MuPDF) — нужны только для растеризации сканированных PDF без извлекаемого текста. Если ни того, ни другого нет на PATH, такие PDF сохраняются на диск.

Изменяемые окружения

Релизы (Мейнтейнеры)

Пакет публикуется в npm как @stubbedev/atlassian-mcp.

Используйте семантическое версионирование. Критические изменения поверхности инструментов должны поднимать минорную версию, пока <1.0.0 (например 0.0.x -> 0.1.0).

По тегу v* в .github/workflows/publish.yml происходит кросс-компиляция Go-бинарника для 14 ОС/архитектур, прикрепление их к GitHub-релизу и публикация npm-обёртки (которая скачивает нужный бинарник при установке).

Процесс релиза:

# choose one: patch | minor | major (also: npm run release:patch / :minor / :major)
npm version patch          # bumps package.json, commits, tags vX.Y.Z
git push origin HEAD --follow-tags

flake.nix читает версию из package.json, поэтому Nix-пакет следит за тем же обновлением автоматически. GitHub Actions собирает и публикует из запушенного тега.

• Рабочий процесс настроен на доверенный издатель OIDC в npm, поэтому секрет NPM_TOKEN не требуется.

Необходимая разовая конфигурация npm:

• В настройках пакета npm добавьте этот GitHub-репозиторий/рабочий процесс как Trusted Publisher

Создание персональных токенов доступа

Jira Server / Data Center

Персональные токены доступны начиная с Jira 8.14.

1. Войдите в свой экземпляр Jira.

2. Нажмите на аватар своего профиля в правом верхнем углу и выберите Профиль.

3. На левой боковой панели выберите Персональные токены доступа.

4. Нажмите Создать токен.

5. Дайте токену имя (например, atlassian-mcp) и, опционально, установите срок действия.

6. Нажмите Создать и скопируйте токен — он будет показан только один раз.

Вставьте токен как значение token в раздел jira вашего конфигурационного файла.

Если ваша версия Jira старше 8.14, можно использовать HTTP Basic Auth, но этот сервер поддерживает только Bearer-токены (PAT).

Bitbucket Server / Data Center

Персональные токены доступа поддерживаются начиная с Bitbucket Server 5.5.

1. Войдите в ваш экземпляр Bitbucket.

2. Нажмите на аватар своего профиля в правом верхнем углу и выберите Управление аккаунтом.

3. В левой боковой панели, в разделе Безопасность, выберите Персональные токены доступа.

4. Нажмите Создать токен.

5. Дайте токену имя (например, atlassian-mcp).

6. Задайте права:

   • Проекты: Чтение

   • Репозитории: Чтение + Запись (Запись нужна для создания пул-реквестов и комментариев)

7. При желании задайте срок действия.

8. Нажмите Создать и скопируйте токен — он будет показан только один раз.

Вставьте токен как значение token в раздел bitbucket вашего конфигурационного файла.

Разработка

Сервер — это один Go-модуль в корне репозитория (без дерева src/).

# Build the binary
go build -o atlassian-mcp .

# Run it
./atlassian-mcp --config /path/to/config.json

# Vet + unit tests
go vet ./...
go test ./...

# Test the tool list
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | ./atlassian-mcp

# Quick release smoke check (build + tools/list validation)
npm run smoke