The Model Context Protocol server for Qrblox — a local stdio package so Claude Desktop, Cursor, and other agents can npx Qrblox the same way FlipLetters ships flipletters-mcp-server.

This package does not reimplement merchant tools. It is a thin stdio proxy to the live Streamable HTTP MCP:

https://api.qrblox.com/mcp/v1 (qrblox-mcp 0.1.0)

📚 Docs: docs.qrblox.com/mcp.html 🔑 Mint a key: app.qrblox.com/settings

Quick start

1. Mint an API key

Merchant tools/call requests send that key as Authorization: Bearer sk-qrblox-....

2. Run with npx

QRBLOX_API_KEY=sk-qrblox-... npx -y qrblox-mcp

Without QRBLOX_API_KEY, the process starts and exits immediately with a clear error pointing at the settings page.

3. Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "qrblox": {
      "command": "npx",
      "args": ["-y", "qrblox-mcp"],
      "env": {
        "QRBLOX_API_KEY": "sk-qrblox-..."
      }
    }
  }
}

Restart Claude Desktop, then ask it to generate a QR code or look up a voice-agent number.

4. Cursor

Add the same stdio server in Cursor MCP settings (.cursor/mcp.json or the MCP panel):

{
  "mcpServers": {
    "qrblox": {
      "command": "npx",
      "args": ["-y", "qrblox-mcp"],
      "env": {
        "QRBLOX_API_KEY": "sk-qrblox-..."
      }
    }
  }
}

Clients that already speak Streamable HTTP can skip this package and call the remote endpoint directly:

{
  "mcpServers": {
    "qrblox": {
      "url": "https://api.qrblox.com/mcp/v1",
      "headers": {
        "Authorization": "Bearer sk-qrblox-..."
      }
    }
  }
}

Environment

Variable	Required	Description
`QRBLOX_API_KEY`	Yes (for `tools/call`)	Merchant key `sk-qrblox-...` from app.qrblox.com/settings. Sent as `Authorization: Bearer`.
`QRBLOX_MCP_URL`	No	Override the remote MCP URL. Defaults to `https://api.qrblox.com/mcp/v1`.

What the proxy does

Speaks MCP over stdio (what Claude Desktop / Cursor spawn).
Forwards tools/list and tools/call to https://api.qrblox.com/mcp/v1 (Streamable HTTP / JSON-RPC).
Attaches Authorization: Bearer $QRBLOX_API_KEY so merchant tools run on the key owner's workspace.

Tool schemas and behavior always come from the live server — this package is not a second implementation.

Tools (from the live server)

Tool	Description
`qrblox.ping`	Confirm reachability + identity for the authenticated merchant.
`qrblox.voice_agent.lookup`	Look up a business in the Voice Agent Phone Book by domain.
`qrblox.voice_agent.register`	Register a voice-agent number for a domain.
`qrblox.merchant.get_profile`	Merchant workspace attached to the key.
`qrblox.qr.list` / `.create` / `.update` / `.get_analytics`	List, create, re-point, and report on QR codes.
`qrblox.audio.create`	Draft an audio code.
`qrblox.menu.create` / `.list` / `.add_item`	Build and extend merchant menus.
`qrblox.challenge.create`	Scan streaks, scan-count games, visit-window or loyalty campaigns.
`qrblox.analytics.scan_summary`	Total scans + by-day series.

Full reference: docs.qrblox.com/mcp.html.

Local development

npm install
npm test

npm test builds the package and runs a short check that the process starts and fails clearly when QRBLOX_API_KEY is missing.

QRBLOX_API_KEY=sk-qrblox-... npm start

Publishing (maintainers)

Do not commit tokens or keys. This package is not published from CI in this PR.

Confirm the unscoped name is still free: npm view qrblox-mcp (it was unpublished / 404 when this package was added). If it is taken, change package.json name to @qrblox/mcp and publish that instead.
Sign in as the Qrblox npm user:
```
npm login
```
From a clean build:
```
npm publish
```
(prepublishOnly runs npm test first.)
Smoke-check: npx -y qrblox-mcp should print the missing-key error until QRBLOX_API_KEY is set.