QRdx

Design styled QR codes, build Wi-Fi, vCard and SMS payloads, and search CC0 styles. Remote; most tools need no key.

View on qrdx.dev

Hosted MCP Server

npx add-mcp 'https://mcp.qrdx.dev/mcp'

Installs into Claude Code, Codex, Cursor and more

Documentation

MCP server (Developers)

URL: https://qrdx.dev/docs/developers/mcp Source: https://github.com/bucharitesh/qrdx/blob/main/apps/docs/content/docs/developers/mcp.mdx

Let Claude, Cursor, VS Code and other AI tools generate styled QR codes with the QRdx MCP server.

QRdx runs a public Model Context Protocol server at:

https://mcp.qrdx.dev/mcp

Use this URL in every client. The same server also answers at https://qrdx.dev/api/mcp, and the connect page shows the public URL on qrdx.dev, on preview deployments and in local development.

It uses the Streamable HTTP transport and keeps no session state. Your AI assistant can call it to design QR codes for any content type with a checked scan score, render QR codes, list the available styles, find community frames and themes, and build correctly formatted payloads for Wi-Fi, contacts, email, SMS and map locations. None of that needs an account or API key. With a QRdx API key on the connection, it can also save a design to your themes and use logos you uploaded (see Use an API key).

Try it in the playground: style a code there, then copy it as design_qr arguments for your assistant.

Setup [#setup]

Claude Code

claude mcp add --transport http qrdx https://mcp.qrdx.dev/mcp

Cursor

Add the server to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "qrdx": {
      "url": "https://mcp.qrdx.dev/mcp"
    }
  }
}

VS Code

Add the server to .vscode/mcp.json in your workspace:

{
  "servers": {
    "qrdx": {
      "type": "http",
      "url": "https://mcp.qrdx.dev/mcp"
    }
  }
}

Other clients

Clients that support remote (Streamable HTTP) servers only need the URL https://mcp.qrdx.dev/mcp. For clients that only run local stdio servers, bridge it with mcp-remote:

{
  "mcpServers": {
    "qrdx": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.qrdx.dev/mcp"]
    }
  }
}

Then ask for what you need, for example:

  • "Make a QR code for https://example.com in our brand blue, #155dfc, with rounded modules."
  • "Create a Wi-Fi QR code for the network Office Guest with password correct-horse-battery."
  • "Generate a contact QR code for Ada Lovelace, ada@example.com, and add it to the README."
  • "Design a Wi-Fi QR code for Cafe Guest in warm browns with a Free Wi-Fi frame, and tell me its scan score."
  • "Find a community frame for a restaurant menu and use it for https://example.com/menu."

Tools [#tools]

ToolWhat it does
design_qrDesigns a code for any content type with the style your assistant chooses, or starting from a built-in theme or a community item, checks its scan score and repairs the style until it is Great. Returns the score, what it changed, the style JSON, a playground link, a PNG and the SVG.
list_optionsLists every value design_qr accepts: content types and their fields, colours and gradients, shapes, frames, borders, logo icons, built-in themes, error correction levels and limits.
generate_qr_codeRenders a QR code with the editor's styles. Returns a PNG image and public image API URLs (SVG, PNG, lossless WebP and vector EPS) ready for Markdown, HTML or print, plus the SVG markup on request.
list_qr_stylesLists body patterns, corner eye and eye dot shapes, border templates, frames, logo icons, error correction levels, defaults and limits.
search_communityFinds published community frames, themes and collections by words, type or tag.
get_community_itemOne community item with the style it applies, ready for design_qr or generate_qr_code.
save_templateSaves a design as a theme in your workspace. Needs an API key.
generate_barcodeDraws an EAN-13, UPC-A, UPC-E, EAN-8, ITF-14, GS1-128, Code 128, Code 39, Data Matrix, PDF417 or Aztec barcode after checking the value (check digits, lengths, characters). Returns a PNG and public barcode API URLs.
save_barcodeSaves a barcode to your workspace's Barcodes. Needs an API key.
qr_payload_wifiBuilds a WIFI: network payload (WPA, WEP or open, optionally hidden) with special characters escaped.
qr_payload_vcardBuilds a vCard 3.0 contact (RFC 2426): name, organization, title, phones, email, website, address and note.
qr_payload_emailBuilds a mailto: link (RFC 6068) with optional cc, bcc, subject and body.
qr_payload_smsBuilds an sms: link (RFC 5724) with an optional message, or the older SMSTO: form.
qr_payload_geoBuilds a geo: location (RFC 5870) from latitude and longitude.

The payload tools return a plain string. Your assistant then passes it as data to generate_qr_code.

design_qr [#design_qr]

design_qr takes the content as a type and its fields, the same types and checks as the editor's content forms (list_options lists them), and an optional style:

{
  "content": { "type": "wifi", "ssid": "Cafe Guest", "password": "sunshine123", "encryption": "WPA" },
  "style": {
    "bgColor": "#FFF7ED",
    "fgColor": "#9A3412",
    "bodyPattern": "rounded",
    "cornerEyePattern": "rounded",
    "frame": { "style": "banner-bottom", "text": "Free Wi-Fi" }
  }
}

Options you leave out get defaults (eyes follow the dot colour, square shapes, margin 4, error correction Q, no frame). QRdx then runs the editor's scan check on the design: it renders the code, decodes it at 96, 160 and 320 px through a phone-camera model, and checks contrast, quiet zone, eye shapes and shape pairs. Below Great (85), it repairs the style, up to three times, changing as little as it can (darker colours that keep their hue, a safer eye shape, less error correction for long content). If that isn't enough, it falls back to a classic black-on-white code with your frame. The result says what was changed and why.

No AI model runs on QRdx's side for design_qr: your assistant picks the style, QRdx validates, checks and repairs it. Content that isn't valid (a WPA password under 8 characters, a malformed email address) is refused with the reason. design_qr has its own limit of 20 calls per minute per IP address.

More inputs:

  • preset: start from a built-in theme by id (list_options lists them). Style options you set win over it.
  • community_item: start from a community frame or theme by id, such as frame:wifi-card. A frame item sits on a classic code; your style options change the code under it.
  • A custom frame: style.frame can be { "style": "custom", "spec": … } with a frame spec, such as a community frame's from get_community_item. It's drawn and scored as it is; repairs change the code, never the frame.
  • style.logo: a quick logo icon (wifi, location, phone, email, link, file, calendar, whatsapp or instagram).
  • Engine options: style.eyeColors (per-eye #RRGGBB colors), moduleScale (dot size, 0.5 to 1), shape (circle for a round code), autoLevel and logoOptions (the logo's size, clear space, position, crop and plate). They're drawn and scored as given; repairs don't change them.

logo_file_id draws a logo you uploaded to QRdx instead, with an API key.

Logos are scored by the modules they cover, as in the editor, so a repair may raise error correction to H or remove the logo. The QRdx mark that the editor shows by default isn't drawn here.

The result's qrdxStyle is the design as the editor's style JSON. Pass it to save_template, to generate_qr_code as style to render the same design at another size, or to the image API's style. playground_url opens the design in the playground: it carries the style only, never the logo or the content, and playgroundLeftOut says what it leaves out.

generate_qr_code inputs [#generate_qr_code-inputs]

The inputs match the image API parameters: data (required), size, fg, bg, eyeColor, dotColor, body, eye, dot, level, margin, template, frame, frameText, logoIcon, logoFileId, item (a community item id) and style (the editor's style JSON: gradients, custom frames and the rest, as design_qr returns it). The flat options win over style, and style wins over item. Set include_svg to true to also get the SVG markup as text, for example to save an .svg file. It is off by default because the markup is often 50 to 150 KB, which would fill the conversation.

generate_qr_code doesn't check the scan score; use design_qr for that. A code with your uploaded logo has no public image URL, since the image API only draws that logo for requests with your key.

The QR card [#qr-card]

In apps that support MCP Apps, design_qr and generate_qr_code also show a QR card in the chat. It has the code, what it encodes (a Wi-Fi code shows its network name, never the password), the size and error correction or the scan score, and an Open in editor button. The editor link carries the style only, like playground_url.

The PNG and SVG buttons depend on what the app allows. Where it can save files from a card, they save them. Otherwise they open the image API URL in your browser, so design_qr's card shows them only in apps that save files: its content never goes in an image URL. Apps may ask you to confirm before a link opens.

Apps without MCP Apps get the same text and image as before. For client developers:

  • The card is the resource ui://qrdx/qr-card (text/html;profile=mcp-app), listed by resources/list. Both tools point to it with _meta.ui.resourceUri.
  • Its data comes in the tool result's _meta, under dev.qrdx/qr-card, which is meant for the card and not the model. The tools return no structuredContent.
  • The card is a single HTML file with its styles and script inline. The only thing it loads is the code's image from the image API (https://api.qrdx.dev, or your own domain when self-hosted), and its content security policy (_meta.ui.csp.resourceDomains) allows that host and nothing else.

If you connected QRdx before the card existed, remove the connector and add it again, or refresh its tools, so the app picks up the new tool metadata.

Community [#community]

search_community finds published community frames, themes and collections, free under CC0, by words (q), type and tag. get_community_item returns one item with the style it applies; pass its id to design_qr as community_item or to generate_qr_code as item. The same data is on the REST API at /v1/community/items.

Item text is written by community members. Names, descriptions, handles, tags and frame labels come back short, on one line and without links, emails or markup, and every result says to treat them as data, not instructions.

Use an API key [#use-an-api-key]

Some tools need a QRdx API key on the connection, sent as Authorization: Bearer qrdx_…:

  • save_template saves a design as a theme, listed under Themes in the dashboard and offered in the editor. It needs a key with codes:write, which Full access keys have. A key of your own workspace saves to your themes; a team key saves to the team's shared themes when its creator is an owner or admin and the plan has team themes. Saves count toward the plan's saved-theme limit (see Plans and limits); over it, the tool returns the API's LIMIT_REACHED error (402). Without a key it returns a 401 error that says how to add one.

  • save_barcode saves a barcode (format, value, an optional title and drawing options) to the key's workspace, listed under Barcodes in the dashboard. It needs a key with codes:write. Every plan saves barcodes, up to 1,000 on Free; over the limit it returns LIMIT_REACHED (402).

  • Logos you uploaded in Dashboard → Files, by file id (logo_file_id in design_qr, logoFileId in generate_qr_code): a PNG or JPEG of up to 1 MB. The key must belong to the workspace that owns the file.

Claude Code

claude mcp add --transport http qrdx https://mcp.qrdx.dev/mcp \
  --header "Authorization: Bearer $QRDX_API_KEY"

Cursor

{
  "mcpServers": {
    "qrdx": {
      "url": "https://mcp.qrdx.dev/mcp",
      "headers": { "Authorization": "Bearer qrdx_…" }
    }
  }
}

VS Code

{
  "servers": {
    "qrdx": {
      "type": "http",
      "url": "https://mcp.qrdx.dev/mcp",
      "headers": { "Authorization": "Bearer qrdx_…" }
    }
  }
}

Keep the key out of shared or committed config files. Calls made with a key count toward the workspace's daily API quota; every other tool works the same with or without one.

Privacy and limits [#privacy-and-limits]

  • The tools render images, check designs, format text and read the public community. Only save_template and save_barcode write anything: the theme or barcode you ask them to save, in the API key's workspace. The server doesn't save the codes you generate.
  • The image URLs that generate_qr_code and generate_barcode return contain the encoded data. Don't share them if the data is private, such as a Wi-Fi password.
  • Requests are limited to 120 per minute per IP address, and design_qr to 20. With a key, save_template is also limited to 30 a minute per user.

Self-hosting and local development [#self-hosting-and-local-development]

The MCP server is part of the QRdx web app, so every instance serves it at /api/mcp:

  • Self-hosted. When NEXT_PUBLIC_APP_URL is your own domain, the connect page, snippets and install links use https://<your-domain>/api/mcp.
  • Local development. bun run dev serves it at http://localhost:3000/api/mcp. The connect page still shows the public URL and offers the local one as a hint, so you can point a client at your machine to test changes to the server before they ship.

Opening /api/mcp in a browser redirects to the connect page. MCP clients never ask for HTML, so they reach the server as usual.