Jira MCP Server (только чтение)

Локальный MCP сервер, который позволяет Claude Code получать контекст тикетов Jira (детали задачи, ветки комментариев, граф ссылок вокруг тикета и результаты поиска JQL), отображаемый в виде компактного Markdown. Вложения-изображения (например, скриншот в тикете о баге в UI) можно загружать для визуального анализа Claude.

Что он намеренно не умеет

Этот сервер строго только для чтения. Он не предоставляет ни одного инструмента, который создаёт, обновляет, переводит, удаляет или комментирует что-либо. Защита многоуровневая:

1. В коде: каждый HTTP-запрос проходит через единственный помощник, который разрешает только GET, с одним исключением из белого списка: POST /rest/api/3/search/jql — операция чтения, которую Atlassian требует отправлять как POST. Любой другой метод вызывает ReadOnlyViolationError, так что будущее изменение, добавляющее вызов записи, громко провалится.

2. На уровне учётных данных: создайте API-токен только с правами на чтение (ниже), чтобы даже ошибка не могла записать.

Related MCP server: JIRA MCP Server

Инструменты

Настройка

1. Создайте API-токен Atlassian

1. Перейдите на https://id.atlassian.com/manage-profile/security/api-tokens.

2. Выберите Создать API-токен с областями (Atlassian отменяет токены без областей).

3. Выберите приложение Jira и отметьте только эти области:

   • read:jira-work

   • read:jira-user

4. Скопируйте токен сразу; он показывается только один раз.

Более старый неограниченный токен также работает; сервер обрабатывает оба автоматически (см. ниже).

2. Настройте .env

cp .env.example .env   # then edit

Обязательные ключи (это вся поверхность конфигурации):

.env находится в .gitignore; никогда не коммитьте его. Настоящие переменные окружения имеют приоритет над файлом. Файл расположен относительно каталога проекта (а не рабочего каталога), поэтому сервер находит его независимо от того, откуда он запущен.

3. Установите зависимости

С помощью uv (предпочтительно, так как в этом репозитории есть uv.lock):

uv sync

Или с помощью обычного pip в виртуальное окружение:

python -m venv .venv
.venv/bin/pip install -r requirements.txt   # Windows: .venv\Scripts\pip

4. Проверьте с помощью --check

.venv/bin/python -m jira_mcp --check            # connectivity + auth only
.venv/bin/python -m jira_mcp --check PROJ-123   # also fetch a ticket in full

Это выводит, был ли найден .env, какой базовый URL был выбран (и понадобился ли запасной вариант с cloud-ID), аутентифицированную учётную запись и, если задан ключ, тикет точно так, как его увидел бы Claude.

Ограниченные и неограниченные токены: проблема базового URL

• Неограниченный токен работает с URL вашего сайта, https://<site>.atlassian.net.

• Ограниченный токен по тому же URL молча не работает, возвращая ответы, похожие на анонимные. Вместо этого он должен вызывать https://api.atlassian.com/ex/jira/{cloudId}.

Вам не нужно знать, какой у вас тип. При запуске сервер проверяет URL сайта с помощью GET /rest/api/3/myself; если это не возвращает реальную учётную запись, он получает ваш cloud ID из {site}/_edge/tenant_info и повторяет попытку через api.atlassian.com. Победитель кэшируется на время жизни процесса и записывается в stderr.

Если обнаружение когда-либо не сработает: _edge/tenant_info не является частью официально поддерживаемого REST API Atlassian (хотя собственная документация поддержки Atlassian ссылается на него), поэтому он может измениться. В этом случае установите ATLASSIAN_CLOUD_ID в .env, чтобы пропустить обнаружение; сообщение об ошибке подскажет, когда это применимо. Вам это почти никогда не понадобится.

Настройка PyCharm

1. Интерпретатор: Settings → Project → Python Interpreter → Add Interpreter → Existing → выберите .venv/bin/python в каталоге проекта. (Если вы запускали uv sync, виртуальное окружение уже существует со всем установленным.)

2. Конфигурация запуска для отладки: Run → Edit Configurations → + → Python:

   • Run: модуль jira_mcp (выберите «module» вместо «script path»)

   • Parameters: --check PROJ-123

   • Working directory: корень проекта (подойдёт что угодно, но так аккуратнее)

Теперь вы можете устанавливать точки останова где угодно (например, в client.py) и отлаживать реальные запросы. Ошибки внутри работающего MCP-сервера в противном случае невидимы.

Подключение к Claude Code

Используйте Python из виртуального окружения по абсолютному пути; просто python не разрешится в виртуальное окружение, когда Claude Code запускает сервер.

macOS/Linux:

claude mcp add jira -- /path/to/PythonProject/.venv/bin/python -m jira_mcp

Windows:

claude mcp add jira -- C:\path\to\PythonProject\.venv\Scripts\python.exe -m jira_mcp

Примечания:

• Всё после -- — это команда, которую запускает Claude; всё до него — собственные параметры Claude.

• Область по умолчанию — local (только вы, только этот проект, хранится в ~/.claude.json). Добавьте --scope project, чтобы поделиться через проверенный в репозитории .mcp.json, или --scope user, чтобы использовать его во всех ваших проектах.

Проверьте подключение

Внутри сессии Claude Code:

• Запустите /mcp; сервер jira должен быть указан как подключённый, с шестью инструментами.

• Или просто спросите: «используй whoami, чтобы проверить подключение jira».

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

Заметки для разработчиков, новых в Python

• Виртуальное окружение (.venv/) — это локальная для проекта копия Python и пакетов этого проекта: эквивалент node_modules, за исключением того, что сам интерпретатор также находится внутри. Поэтому Claude Code нужно передавать .venv/bin/python по абсолютному пути: нет глобальной установки, на которую можно положиться.

• asyncio.run(...) необходим, потому что асинхронные функции в Python не выполняются просто при вызове; вызов возвращает объект корутины, и что-то должно им управлять. Здесь нет фонового цикла событий, как в Node; asyncio.run() создаёт цикл, выполняет одну корутину до завершения и разрушает цикл. MCP-сервер делает это внутренне через mcp.run(); режим --check делает это явно.

• Декораторы (@mcp.tool) — это функции, которые получают функцию, определённую ниже, и регистрируют/оборачивают её, как фабрика промежуточного ПО, применяемая во время определения. Декоратор FastMCP читает имя функции, подсказки типов и docstring, чтобы сгенерировать схему инструмента MCP, которую видит Claude; docstring является документацией API инструмента.

• python -m jira_mcp запускает __main__.py пакета — ближайший аналог записи bin в npm. Он работает из любого каталога, потому что uv sync установил проект в виртуальное окружение.