Confluence MCP Server

Сервер Model Context Protocol (MCP) для интеграции Atlassian Confluence с Claude Code.

Возможности

• 🔍 Поиск по страницам Confluence с использованием CQL (Confluence Query Language)

• 📄 Чтение страниц по ID или заголовку

• ✏️ Создание и обновление страниц

• 🏷️ Управление метками и метаданными

• 📁 Список пространств и вложений

• 🔐 Безопасная базовая аутентификация с помощью API-токенов

Related MCP server: mcp-confluence

Установка

Предварительные требования

• Node.js 18+ и npm

• Учетная запись Atlassian Confluence Cloud

• API-токен (см. раздел «Конфигурация» ниже)

Настройка

git clone https://github.com/gkrauchunas-arlo/confluence-mcp.git
cd confluence-mcp
npm install

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

1. Скопируйте .env.example в .env:

   cp .env.example .env

2. Введите свои учетные данные Atlassian в .env:

   ATLASSIAN_SITE=your-domain.atlassian.net
   ATLASSIAN_EMAIL=your-email@example.com
   ATLASSIAN_API_TOKEN=your-token

Получение API-токена:

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

2. Нажмите "Create API token"

3. Дайте ему имя (например, "Claude Code MCP") и скопируйте токен в .env

Тестирование

# Test Confluence API connectivity
node test-confluence.js

# Test MCP protocol (via stdio)
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

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

Вариант 1: CLI (рекомендуется)

claude mcp add --transport stdio confluence \
  --env ATLASSIAN_SITE="your-domain.atlassian.net" \
  --env ATLASSIAN_EMAIL="your-email@example.com" \
  --env ATLASSIAN_API_TOKEN="your-token" \
  -- node /absolute/path/to/confluence-mcp/index.js

Замените /absolute/path/to/ на ваш фактический путь установки (например, /home/username/confluence-mcp).

Вариант 2: Файл конфигурации

Добавьте в файл конфигурации MCP для Claude Code:

{
  "mcpServers": {
    "confluence": {
      "command": "node",
      "args": ["/absolute/path/to/confluence-mcp/index.js"],
      "env": {
        "ATLASSIAN_SITE": "your-domain.atlassian.net",
        "ATLASSIAN_EMAIL": "your-email@example.com",
        "ATLASSIAN_API_TOKEN": "your-token"
      }
    }
  }
}

Расположение файлов конфигурации:

• Linux: ~/.config/claude-code/mcp_servers.json или ~/.claude/config/mcp_servers.json

• macOS: ~/Library/Application Support/claude-code/mcp_servers.json

• Windows: %APPDATA%\claude-code\mcp_servers.json

После настройки перезапустите Claude Code, чтобы активировать MCP-сервер.

Доступные инструменты

Поиск и навигация

• confluence_search - Поиск CQL по всему контенту

  • Параметры: query (строка), limit (число, необязательно), spaceKey (строка, необязательно)

  • Пример: Поиск страниц с "API" в заголовке внутри определенного пространства

• confluence_list_spaces - Список всех пространств

  • Параметры: limit (число, необязательно, по умолчанию: 25)

  • Возвращает: Список всех пространств Confluence, доступных вашей учетной записи

Чтение контента

• confluence_get_page - Получение страницы по ID

  • Параметры: pageId (строка)

  • Возвращает: Полные данные страницы, включая контент, версию и метаданные

• confluence_get_page_by_title - Поиск страницы по заголовку и пространству

  • Параметры: title (строка), spaceKey (строка)

  • Возвращает: Страницу, соответствующую точному заголовку в указанном пространстве

• confluence_get_space - Получение информации о пространстве

  • Параметры: spaceKey (строка)

  • Возвращает: Метаданные и конфигурацию пространства

• confluence_get_attachments - Список вложений страницы

  • Параметры: pageId (строка)

  • Возвращает: Список всех вложений на странице

Создание и редактирование

• confluence_create_page - Создание новой страницы

  • Параметры: title (строка), spaceKey (строка), content (HTML-строка), parentId (строка, необязательно)

  • Создает новую страницу в указанном пространстве, опционально как дочернюю для другой страницы

• confluence_update_page - Обновление существующей страницы

  • Параметры: pageId (строка), title (строка), content (HTML-строка), version (число)

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

Метаданные

• confluence_add_labels - Добавление меток к странице

  • Параметры: pageId (строка), labels (массив строк)

  • Добавляет одну или несколько меток/тегов к странице для классификации

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

После подключения к Claude Code вы можете использовать естественный язык для взаимодействия с Confluence:

Поиск страниц

Find all pages about "API documentation" in Confluence

Чтение страницы

Read the contents of Confluence page with ID 12345

Создание новой страницы

Create a new page in the DEV space titled "API Guidelines" with this content:
<h1>API Guidelines</h1>
<p>This document describes our API design principles.</p>

Обновление страницы

Update Confluence page 12345 to add a new section about authentication

Добавление меток

Add labels "documentation" and "api" to Confluence page 12345

Примеры CQL-запросов

Инструмент confluence_search поддерживает Confluence Query Language (CQL):

type=page AND title~"API"
type=page AND space=DEV
type=page ORDER BY lastmodified DESC
type=page AND label=documentation
type=page AND creator=currentUser()

Справочник API

Этот MCP-сервер использует Confluence REST API:

• Базовый URL: https://{site}.atlassian.net/wiki/rest/api

• Аутентификация: Basic Auth с email + API-токен

• Версия API: Cloud REST API (стабильная)

• Полная документация API

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

"Authentication failed"

• Проверьте ваш email и API-токен в .env

• Убедитесь, что токен не истек (API-токены не имеют срока действия, но могут быть отозваны)

• Убедитесь, что вы используете API-токен, а не пароль от учетной записи Atlassian

"MCP tools not showing up"

• Полностью перезапустите Claude Code (закройте и откройте снова)

• Проверьте логи сервера на наличие ошибок, запустив node index.js напрямую

• Проверьте конфигурацию с помощью claude mcp list

• Убедитесь, что в конфигурации используется полный абсолютный путь

Ошибки "Permission denied"

• Убедитесь, что ваша учетная запись Atlassian имеет доступ к запрашиваемым пространствам/страницам

• Некоторые операции требуют специальных разрешений (например, права администратора пространства для создания страниц)

• Проверьте разрешения пространства в веб-интерфейсе Confluence

"Page version conflict"

• При обновлении страницы необходимо указать текущий номер версии

• Сначала получите текущую версию с помощью confluence_get_page

• Сервер автоматически увеличит версию на 1

Формат контента

Страницы Confluence используют Storage Format (HTML с макросами Confluence). Для простых страниц подходит стандартный HTML:

<h1>Heading</h1>
<p>Paragraph with <strong>bold</strong> and <em>italic</em> text.</p>
<ul>
  <li>Bullet point 1</li>
  <li>Bullet point 2</li>
</ul>
<pre><code>Code block</code></pre>

Для расширенных функций см. документацию по формату хранения Confluence.

Архитектура

Построено на:

• @modelcontextprotocol/sdk - реализация протокола MCP

• axios - HTTP-клиент для Confluence REST API

• dotenv - управление конфигурацией

Сервер работает как stdio-based MCP-сервер, взаимодействуя с Claude Code через JSON-RPC 2.0 по стандартному вводу/выводу.

Разработка

Структура проекта

confluence-mcp/
├── index.js              # Main MCP server implementation
├── package.json          # Dependencies and scripts
├── test-confluence.js    # Confluence API connectivity tests
├── test-mcp.js           # MCP protocol tests (WIP)
├── .env.example          # Example configuration
├── .env                  # Your configuration (gitignored)
└── README.md             # This file

Запуск тестов

# Test Confluence API directly
node test-confluence.js

# Test MCP server via stdio
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"0.1.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | node index.js

Вклад в проект

Вклады приветствуются! Пожалуйста:

1. Сделайте форк репозитория

2. Создайте ветку для функции (git checkout -b feature/amazing-feature)

3. Внесите изменения с тестами

4. Закоммитьте изменения (git commit -m 'feat: add amazing feature')

5. Отправьте изменения в ветку (git push origin feature/amazing-feature)

6. Откройте Pull Request

Известные ограничения

1. Загрузка вложений - еще не реализована (требует кодирования multipart/form-data)

2. Форматирование текста - поддерживается только базовый HTML, макросы Confluence могут быть сложными

3. Пагинация - большие наборы результатов ограничены параметром limit

4. Разрешения - API возвращает только контент, доступный аутентифицированному пользователю

Лицензия

ISC

Благодарности

• Архитектура вдохновлена rovo-mcp

• Создано для Claude Code

• Использует Model Context Protocol

Поддержка

• Проблемы: https://github.com/gkrauchunas-arlo/confluence-mcp/issues

• Документация API Atlassian: https://developer.atlassian.com/cloud/confluence/rest/

• Спецификация MCP: https://modelcontextprotocol.io/specification

Создано: gkrauchunas-arlo Статус: Стабильная версия v1.0.0 - Все основные функции реализованы и протестированы