qrtap-mcp — QRTap for AI agents

An MCP stdio server that lets Claude, or any MCP-compatible assistant, run a QRTap workspace: editable QR codes and short links, public pages, guest reviews, booking requests and conditional redirects.

Русская версия: README.ru.md.

Why it exists

A QRTap code encodes a permanent short link, and the destination behind that link stays editable forever. Print a code on a menu, a price list, a shop window or a business card once — then change where it leads as often as you need. Nothing is reprinted.

That makes the product a good fit for an agent: "put a QR on the summer menu", "point the sticker at the new price list", "issue 120 codes for the branches, one per branch", "are there new bookings?" are all one or two tool calls.

Related MCP server: qr-maker

Install

npx -y qrtap-mcp        # run the stdio server
npm i -g qrtap-mcp      # or install the qrtap-mcp binary

Node 20 or newer, and nothing else: the package is compiled JavaScript with zero runtime dependencies, so npx fetches about 22 kB and the server is up — no toolchain download on first run. It speaks MCP on stdin/stdout and logs to stderr only.

Configuration

Where to get a key. The workspace owner issues it in the QRTap cabinet at app.qrtap.kg/workspace/api. The key is shown once, carries the rights of the whole workspace, and can be revoked there at any time. A key can be issued on any plan, including the free one — you can try the integration before paying. What the plan changes is the budget and the batch endpoints, not the door; see Limits and plans below and app.qrtap.kg/pricing.

Treat the key like a password: keep it in the MCP client's env block, not in a prompt, a repository or a shared document.

Claude Desktop

Settings → Developer → Edit Config, then add to claude_desktop_config.json:

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

Claude Code

claude mcp add qrtap --env QRTAP_API_KEY=qrtap_key_XXXX -- npx -y qrtap-mcp

Cursor, Windsurf, VS Code and other MCP clients

The same entry works anywhere that accepts the standard mcpServers shape — .cursor/mcp.json, .mcp.json at a project root, or the client's own settings file:

{
  "mcpServers": {
    "qrtap": {
      "command": "npx",
      "args": ["-y", "qrtap-mcp"],
      "env": { "QRTAP_API_KEY": "qrtap_key_XXXX" }
    }
  }
}

Tools

Twenty tools over the public REST API v1. Read operations are safe to call freely; the four marked public effect change what real customers see, and their descriptions tell the agent to confirm with the user first.

Codes and short links

Analytics

Scan analytics are anonymous and aggregate by design: totals, a per-day series and a device split. Bots are excluded, and no visitor IPs or user-agents are stored, so there are no per-person records for an agent to ask for.

Public pages (/a/{slug})

Reviews and bookings

Smart Links (conditional redirects)

Two rules an agent should know

Read before you overwrite. qrtap_update_page and qrtap_set_smart_rules replace their payload wholesale — anything you omit is erased. Fetch the current state with qrtap_get_page / qrtap_get_smart_rules, merge your change into it, send the whole object back.

Set external_ref on batches. Creation is idempotent by external_ref, so a retried call returns the existing code instead of minting a duplicate. It is what makes a partly failed batch safe to re-run.

Printable artifacts

png_url and svg_url come back on every code. For a print shop, request a PDF directly — artifact endpoints need the same Bearer key:

curl -H "Authorization: Bearer $QRTAP_API_KEY" \
  "https://app.qrtap.kg/api/v1/codes/$CODE_ID/qr?format=pdf" -o code.pdf

format is png | svg | pdf; size sets PNG width (256–3000, ~2000 for print). PNG output is decode-verified before it is returned. Rendering is not exposed as a tool because the result is a binary file rather than text an agent can reason over.

Ready-made agent skills

Step-by-step recipes for the common jobs — a menu you can change without reprinting, a specialist's page in five minutes, one QR for reviews on 2GIS/Google/Yandex, issuing a batch of codes, working the booking inbox — live in skills/ in the repository. Each one is a single self-contained markdown file you can hand to an assistant.

Limits and plans

Two budgets apply to every /api/v1 call: a per-minute brake and a per-day quota, both set by the workspace plan.

The free tier exists so a developer or an agent can try the integration before buying: 100 calls a day is enough to build and demo, not to run a business on.

Over a budget the API answers 429 and says which one ran out — {"error":"rate_limited", "scope":"minute"} means wait seconds, {"error":"quota_exceeded","scope":"day"} means wait for UTC midnight. Both carry Retry-After and the X-RateLimit-Limit / -Remaining / -Reset headers, and the tool result surfaces all of it verbatim so an agent can back off instead of hammering.

Two calls are worth preferring on any plan: qrtap_create_codes_bulk over a loop, and qrtap_list_codes(include_stats=true) over per-code stats requests.

qrtap_create_codes_bulk needs a paid plan. On a free workspace it answers 402 plan_required with the current plan and an upgrade URL; the fallback is a loop of qrtap_create_code within the daily quota. Current plan limits live in one place in the platform — API_PLAN_LIMITS — and the table above tracks it.

Errors

API failures come back as ordinary tool results with isError: true, carrying the HTTP status and the response body as text, so the agent can read and explain them rather than crash. Only an unknown tool name is a JSON-RPC error (-32602).

Licence and terms — where the line is

The client code in this package is MIT-licensed: read it, fork it, vendor it, ship it inside your own product. The LICENSE file is the whole of the grant.

That licence covers this thin client and nothing else. Access to the QRTap API is a separate matter, governed by your QRTap plan and the QRTap terms of use: the service, the hosted platform and the data in your workspace remain QRTap's. An MIT licence on the client is not an entitlement to the API — you still need a valid key on a plan that includes API access, and the usual limits and terms apply.

Development

All commands run from this package directory, in the monorepo and in the public mirror alike:

npm install          # first time only
npm test             # vitest: tool→HTTP mapping and MCP dispatch
npm run typecheck

Smoke test by hand — one JSON-RPC message per line:

npm run build    # dist/ must exist first
QRTAP_API_KEY=qrtap_key_XXXX node bin/qrtap-mcp.mjs <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/list"}
EOF

The published package is compiled JavaScript in dist/ and has zero runtime dependencies — npx -y qrtap-mcp downloads about 22 kB and starts on plain Node, with no toolchain to fetch first. prepack rebuilds dist/ on every npm pack and npm publish, so an unbuilt or stale package cannot be shipped.

npm run build     # tsc -p tsconfig.build.json → dist/

TypeScript sources live in src/ in the repository (MIT, see below) but are not in the tarball. The MCP stdio protocol is implemented directly in src/server.ts; imports carry explicit .js extensions because tsc does not rewrite specifiers and the emitted ESM has to resolve under plain Node.

About this repository

This is the published source of the qrtap-mcp npm package: the server, its tests and the agent skills. The rest of the QRTap platform (web app, API, database) is closed and lives in a private repository, so the history here starts at the first public release rather than at the first commit.

One test is intentionally absent. plan-limits.test.ts reads the plan grid out of the platform's database package and checks that the numbers in this README match what is actually sold; it can only run where both halves exist, so it stays in the private repository.

Issues and pull requests about the server, the skills or the docs are welcome here.

Links

• API reference and keys — app.qrtap.kg/developers

• OpenAPI spec — app.qrtap.kg/openapi.json

• Plans and limits — app.qrtap.kg/pricing

• Issues — github.com/IlyaShurf/qrtap-mcp/issues

MIT © 2026 QRTap (ИП Шуренков И.П., Kyrgyz Republic)