Сервер MCP QR Branding

Спілкуйтеся зі своїм редактором або настільним ШІ-застосунком і доручайте йому генерувати QR-коди через рушій QR Branding. Сервер MCP обгортає публічний API у набір інструментів, які може викликати будь-який клієнт, сумісний із MCP. Користуватися ним можна двома способами:

• Віддалений сервер https://qr-branding.com/mcp: нічого встановлювати не потрібно, достатньо вставити URL і свій ключ API в клієнт.
• Локальний сервер, пакет npm @qr-branding/mcp-server (Node 20+), який ваш клієнт запускає через stdio.

Обидва надають ті самі сім інструментів і автентифікуються тим самим ключем API QR Branding. Вихідний код: mcp-server/.

Що ви отримуєте

Сім інструментів, зіставлених із публічним шлюзом за адресою https://qr-branding.com/api/v1/*:

qr_build_vcard підтримує такі поля: firstName (обов’язкове), lastName, organization, phone, email і url. Поштова адреса, посада й нотатки поки не підтримуються. qr_build_geo приймає лише latitude і longitude (без висоти).

Растрові формати (PNG, JPG, WEBP) і SVG повертаються як вбудовані блоки зображень, тож клієнти, що відображають зображення MCP, показують QR прямо в чаті. PDF вбудувати не можна: локальний сервер записує його у тимчасовий файл і повертає шлях; віддалений сервер повертає його як вбудований ресурс application/pdf.

Передумови

1. Ключ API — увійдіть на qr-branding.com, перейдіть у Кабінет → Ключі API, натисніть Згенерувати ключ і одразу скопіюйте значення qrb_…. Більше ви його не побачите, але можна випустити ще ключі.
2. План Studio — API потребує активного пакета Studio. З будь-яким іншим планом виклики інструментів завершуються помилкою studio_required, а помилка доходить до моделі з підказкою перейти на Studio. Генерації ШІ також витрачають кредити ШІ Studio (out_of_api_credits, коли вони закінчаться).
3. Node 20+ — лише для локального сервера, на машині, де працює процес MCP (зазвичай це ваш ноутбук). Встановленням займається npx.

Віддалений сервер (Streamable HTTP)

Ендпоінт — https://qr-branding.com/mcp, він працює з транспортом Streamable HTTP протоколу MCP (без стану, відповіді JSON). Надсилайте ключ в одному з двох заголовків:

• Authorization: Bearer qrb_PASTE_YOUR_KEY (так налаштовує більшість клієнтів)
• X-API-Key: qrb_PASTE_YOUR_KEY (той самий заголовок, що й у REST API)

Запит без чинного ключа отримує 401 із заголовком WWW-Authenticate: Bearer.

Claude Code (CLI)

claude mcp add --transport http qr-branding https://qr-branding.com/mcp \
  --header "Authorization: Bearer qrb_PASTE_YOUR_KEY"

Виконайте /mcp у сесії, щоб переконатися, що сервер підключено, і попросіть, наприклад, «згенеруй QR для https://qr-branding.com з модулями у формі листка та золотим кольором»; Claude викличе qr_generate.

Cursor

~/.cursor/mcp.json (або Settings → MCP):

{
  "mcpServers": {
    "qr-branding": {
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

VS Code (режим агента GitHub Copilot)

.vscode/mcp.json у вашому робочому просторі:

{
  "servers": {
    "qr-branding": {
      "type": "http",
      "url": "https://qr-branding.com/mcp",
      "headers": { "Authorization": "Bearer qrb_PASTE_YOUR_KEY" }
    }
  }
}

Інші клієнти

Будь-який клієнт, що підтримує Streamable HTTP із власними заголовками, працює з тією самою парою url + headers. Клієнт, який запускає лише сервери stdio, може скористатися локальним сервером.

Користувацькі конектори claude.ai і Claude Desktop

Користувацькі конектори, додані з claude.ai (вебверсія та налаштування конекторів Claude Desktop), автентифікуються через OAuth, якого сервер MCP QR Branding поки не підтримує: вони не можуть надіслати заголовок із ключем API. Доки цього немає, використовуйте локальний сервер у Claude Desktop (нижче) або Claude Code з віддаленим сервером.

Локальний сервер (npm, stdio)

Ваш клієнт запускає npx @qr-branding/mcp-server і обмінюється JSON-RPC через stdin/stdout процесу. Ключ задається в змінній середовища QR_BRANDING_API_KEY.

Claude Code (CLI)

claude mcp add qr-branding --env QR_BRANDING_API_KEY=qrb_PASTE_YOUR_KEY -- npx -y @qr-branding/mcp-server

Claude Desktop (macOS / Windows)

Відкрийте файл конфігурації:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Повністю закрийте Claude Desktop і відкрийте знову. Сервер QR Branding має з’явитися як доступний у меню інструментів біля поля введення повідомлення.

Cursor

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Перезапустіть Cursor. Інструменти доступні і агентові в чаті, і Composer.

ChatGPT Desktop

ChatGPT Desktop читає ~/.openai/chatgpt/mcp-config.json (шлях може відрізнятися залежно від версії — перевірте в Settings → Beta features → Model Context Protocol):

{
  "mcpServers": {
    "qr-branding": {
      "command": "npx",
      "args": ["-y", "@qr-branding/mcp-server"],
      "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
    }
  }
}

Continue (розширення VS Code / JetBrains)

У конфігурації Continue (~/.continue/config.json або .continue/config.json робочого простору), у розділі mcpServers:

"mcpServers": [
  {
    "name": "qr-branding",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
]

Zed

Відкрийте ~/.config/zed/settings.json і додайте в context_servers:

"context_servers": {
  "qr-branding": {
    "source": "custom",
    "command": "npx",
    "args": ["-y", "@qr-branding/mcp-server"],
    "env": { "QR_BRANDING_API_KEY": "qrb_PASTE_YOUR_KEY" }
  }
}

Змінні середовища (локальний сервер)

Перевірка роботи

Віддалений сервер: виведіть список інструментів за допомогою curl:

curl -s https://qr-branding.com/mcp \
  -H "Authorization: Bearer qrb_PASTE_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Локальний сервер: запустіть димовий тест із вихідного коду:

cd mcp-server
npm install
QR_BRANDING_API_KEY=qrb_xxx npm run smoke
QR_BRANDING_API_KEY=qrb_xxx SMOKE_GENERATE=1 npm run smoke

Димовий тест опитує /api/v1/qr/ping і /api/v1/qr/templates, виводить кількість шаблонів і (з SMOKE_GENERATE=1) наскрізно генерує крихітний тестовий QR.

Вартість і обмеження

• Виклики генерації: ручна генерація, шаблони й допоміжні інструменти вмісту не витрачають кредитів; генерація ШІ на наших ключах (qr_generate_ai) витрачає один кредит ШІ Studio. Виклики списків і метаданих шаблонів теж не витрачають кредитів. Див. Ціни й кредити.
• Ліміти запитів — це ліміти шлюзу: див. огляд API. На віддаленому сервері кожен виклик інструмента рахується як один запит у межах хвилинного ліміту та добової квоти вашого ключа; рукостискання й tools/list враховуються лише в ліміті на мережу.
• Вартість з боку ШІ-асистента залежить від тарифів вашого асистента (використання Claude, підписка ChatGPT тощо). Сам сервер MCP безкоштовний.

Конфіденційність і безпека

• Сервер MCP пересилає ваші промпти й усі передані URL/тексти на qr-branding.com. Жодної сторонньої телеметрії, жодних SDK аналітики.
• Ключ API зберігається в конфігурації вашого клієнта — він ніколи не з’являється в історії чату чи контексті моделі. Віддалений сервер отримує його лише через HTTPS і звіряє з хешем, як і REST API.
• Змінюйте ключ будь-коли в Кабінет → Ключі API — старі ключі відкликаються миттєво.

Усунення несправностей

• «QR_BRANDING_API_KEY not set» (локально): змінна середовища не дійшла до запущеного процесу npx. Переконайтеся, що JSON коректний, і перезапустіть застосунок-хост.
• 401 invalid_api_key / missing_api_key (віддалено): заголовок не дійшов або ключ відкликано. Перевірте заголовок Authorization: Bearer qrb_… у конфігурації клієнта.
• studio_required — у вашому обліковому записі немає активного пакета Studio (Starter і Pro містять лише редактор). Придбайте Studio на сторінці цін.
• out_of_api_credits — кредити ШІ Studio закінчилися. Поповніть їх на сторінці цін.
• Зображення не відображається вбудовано: ваш клієнт, імовірно, не підтримує вміст-зображення MCP. Растрові зображення та SVG використовують тип вмісту-зображення зі специфікації; PDF повертаються як шлях до файлу (локально) або вбудований ресурс (віддалено).
• Помилки мережі / тайм-аути: шлюз розташований за адресою https://qr-branding.com. Якщо ваша мережа його блокує, перевизначте QR_BRANDING_API_BASE_URL (локальний сервер).

Що далі

Ми відстежуємо ці пункти для наступних випусків:

• OAuth на віддаленому сервері, щоб його можна було додати як користувацький конектор у claude.ai та інших клієнтах, які цього вимагають.
• Інструмент qr_dynamic_create, що створює друковані динамічні QR (редиректор /q/{slug}), не виходячи з чату.
• Обробники ресурсів для перегляду шаблонів як ресурсів MCP (щоб клієнти з вибором ресурсів могли показувати їх у своєму інтерфейсі).

Створюйте issues або запити на функції в репозиторії. Вихідний код пакета лежить в тому самому монорепозиторії, що й рушій.