QR Branding MCPサーバー

エディタやAIデスクトップアプリに話しかけるだけで、QR Brandingエンジン経由でQRコードを生成できます。MCPサーバーは公開APIをツールの集合としてラップし、MCP対応のクライアントなら誰でも呼び出せます。利用方法は2通りあります。

リモートサーバー https://qr-branding.com/mcp: インストール不要で、URLとAPIキーをクライアントに貼り付けるだけです。
ローカルサーバー: npmパッケージ @qr-branding/mcp-server（Node 20以上）。クライアントがstdio経由で起動します。

どちらも同じ7つのツールを公開し、同じQR Branding APIキーで認証します。ソースコード: mcp-server/

提供される機能

https://qr-branding.com/api/v1/* の公開ゲートウェイに対応する7つのツールです。

ツール	内容
`qr_generate`	手動生成: `QrConfig` の実用的なサブセット（コンテンツ、色、モジュールとファインダーの形状、ECCレベル、出力形式とサイズ、任意のロゴとキャプション）を渡します。レンダリングされたPNG/JPG/WEBP/SVG/PDFを返します。
`qr_generate_ai`	サーバー側のAIプロンプト → QR。「水彩の夕焼け」のようなプロンプトとコンテンツのURLまたはテキストを渡すと、エンジンが色と形状を選んでレンダリングします。
`qr_list_templates`	118種類のデザイン済みテンプレート（ID、名前、説明、プレビューサムネイルのURL）を閲覧します。
`qr_generate_from_template`	テンプレートをIDでレンダリングし、呼び出しごとに上書きできます。コンテンツの変更、色の差し替え、出力形式の調整が可能です。
`qr_build_wifi`	Wi-Fi認証情報（`WIFI:T:WPA;S:...;P:...;;`）をエンコードし、文字列とQRの両方を返します。
`qr_build_vcard`	連絡先カード（vCard）をエンコードし、文字列とQRを返します。
`qr_build_geo`	緯度と経度から `geo:` URIをエンコードし、文字列とQRを返します。

qr_build_vcard が対応するフィールドは firstName（必須）、lastName、organization、phone、email、url です。住所、役職、メモにはまだ対応していません。qr_build_geo は latitude と longitude のみを受け取ります（高度は不可）。

ビットマップ形式（PNG、JPG、WEBP）とSVGはインライン画像コンテンツブロックとして返るため、MCPの画像を表示できるクライアントではチャット内でそのままQRが表示されます。PDFはインライン化できません。ローカルサーバーは一時ファイルに書き出してそのパスを返し、リモートサーバーは埋め込みの application/pdf リソースとして返します。

前提条件

APIキー — qr-branding.com にサインインし、ダッシュボード → APIキーを開いてキーを生成をクリックし、qrb_… の値をその場でコピーします。この値は二度と表示されませんが、キーは追加で発行できます。
Studio プラン — API には有効な Studio パックが必要です。それ以外のプランでは、ツール呼び出しが studio_required で失敗し、アップグレードの案内を添えたエラーがモデルに届きます。AI 生成ではさらに Studio の AI クレジットを消費します（使い切ると out_of_api_credits）。
Node 20以上 — ローカルサーバーを使う場合のみ、MCPプロセスを動かすマシン（通常はお使いのノートPC）に必要です。インストールは npx が行います。

リモートサーバー (Streamable HTTP)

エンドポイントは https://qr-branding.com/mcp で、MCPのStreamable HTTPトランスポート（ステートレス、JSONレスポンス）を使います。キーはどちらかのヘッダーで送信します。

Authorization: Bearer qrb_PASTE_YOUR_KEY（ほとんどのクライアントが設定する形式）
X-API-Key: qrb_PASTE_YOUR_KEY（REST APIと同じヘッダー）

有効なキーがないリクエストには、WWW-Authenticate: Bearer ヘッダー付きで 401 が返ります。

Claude Code (CLI)

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

セッション内で /mcp を実行してサーバーが接続されていることを確認し、「https://qr-branding.com のQRを、葉型のモジュールとゴールドの色で生成して」のように頼むと、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（Web、およびClaude Desktopのコネクタ設定）から追加するカスタムコネクタはOAuthで認証しますが、QR Branding MCPサーバーはまだOAuthに対応していないため、APIキーのヘッダーを送れません。対応するまでは、Claude Desktopではローカルサーバー（下記）、Claude Codeではリモートサーバーを使ってください。

ローカルサーバー (npm, stdio)

クライアントが npx @qr-branding/mcp-server を起動し、プロセスのstdin/stdout経由でJSON-RPCをやり取りします。キーは環境変数 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" }
  }
}

環境変数 (ローカルサーバー)

変数	既定値	変更する理由
`QR_BRANDING_API_KEY`	（必須）	`qrb_…` キーです。未設定の場合、サーバーは分かりやすいエラーを出して起動を拒否します。
`QR_BRANDING_API_BASE_URL`	`https://qr-branding.com`	ステージング環境やセルフホストのゲートウェイを指定します。開発時に便利です。

動作確認

リモートサーバー: 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をエンドツーエンドで生成します。

費用と制限

生成の呼び出し: 手動生成、テンプレート、コンテンツヘルパーはクレジットを消費しません。当社キーによる AI 生成（qr_generate_ai）は Studio の AI クレジットを1つ消費します。一覧やテンプレートのメタデータの呼び出しもクレジットを消費しません。料金とクレジットを参照してください。
レート制限はゲートウェイのものです。APIの概要を参照してください。リモートサーバーでは、ツール呼び出し1回がキーの分あたりの制限と1日の上限に対して1リクエストとして数えられます。ハンドシェイクと tools/list はネットワーク単位の制限にのみ計上されます。
AIアシスタント側の費用は、お使いのアシスタントの料金体系（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 の AI クレジットを使い切りました。料金から追加してください。
画像がインライン表示されない: クライアントがMCPの画像コンテンツに対応していない可能性があります。ビットマップとSVGは仕様の画像コンテンツタイプを使い、PDFはファイルパス（ローカル）または埋め込みリソース（リモート）として返ります。
ネットワークエラー / タイムアウト: ゲートウェイは https://qr-branding.com にあります。ネットワークでブロックされている場合は、QR_BRANDING_API_BASE_URL を上書きしてください（ローカルサーバー）。

今後の予定

今後のリリースに向けて、次の項目を検討しています。

リモートサーバーのOAuth対応。claude.aiなど、それを必須とするクライアントでカスタムコネクタとして追加できるようにします。
印刷可能なダイナミックQR（/q/{slug} のリダイレクター）をチャットから離れずに作成する qr_dynamic_create ツール。
テンプレートをMCPリソースとして閲覧するためのリソースハンドラー（リソースピッカーを持つクライアントのUIで表示できるようにします）。

Issueや機能リクエストはリポジトリにお寄せください。パッケージのソースはエンジンと同じモノレポにあります。