Qrx MCP Server

QRX

Art QR codes that always scan.

QRX makes branded, print-ready QR codes for posters, menus, packaging and signage. Describe the look you want and give it a link: QRX paints the code into artwork, checks that it decodes before handing it over, and points it at a hosted short link, https://qrx.to/<id> on qrx.codes, that you can re-point later on a paid plan. This repository connects QRX to Claude, ChatGPT, Cursor, VS Code and other MCP clients through the remote server at https://qrx.codes/mcp.

Listed in the official MCP Registry as codes.qrx/mcp.

What you can do

• Make a code: "Make a QR code for https://example.com/menu that looks like a watercolour café street."
• Check on it: generation usually takes under a minute; the agent waits for it and returns the image and short link.
• Find old codes: list the codes on your account, newest first.
• Re-point a code: send an existing printed code to a new link, with no reprint (on a paid plan).
• Check your allowance: see how many codes you have left today.

Connection details

Sign in or use an API key

Every client below that takes a URL signs in with your QRX account: add the URL, then sign in (free) when the client asks as it connects. There is nothing to copy or keep secret.

For clients that only run local servers, and for scripts and CI, use an API key. Any client below can use one instead of signing in:

1. Sign in at qrx.codes (free).

2. Open qrx.codes/developers/keys and create a key. It starts with qrx_.

3. Keep it secret. The examples below read it from an environment variable called QRX_API_KEY wherever the client allows that:

   # macOS / Linux
   export QRX_API_KEY="qrx_live_…"
   

   # Windows PowerShell (current user, persistent)
   [Environment]::SetEnvironmentVariable("QRX_API_KEY", "qrx_live_…", "User")
   

Revoke a key at any time from the same page.

Install

Option A: plugin (MCP server, the QRX skill and the code card)

/plugin marketplace add qrxcodes/qrx-mcp
/plugin install qrx@qrx

Then run /mcp, select qrx and sign in to QRX. The plugin also adds the qrx skill, which teaches Claude how to write good art prompts, wait for the code and prepare it for print.

The plugin also shows each finished code in the transcript, under the QRX tool call: its picture, the short link it scans to and a link to its QRX page, with a line while the code is still being painted. It is a mod, so it draws in the terminal (Claude Code 2.1.287 or later) and the Desktop app's Code tab; it fetches the picture with curl. Terminals with kitty graphics (kitty, Ghostty) show the full picture; other terminals show it in coloured character cells, with a link to the full-quality image.

Option B: MCP server only

claude mcp add --transport http qrx https://qrx.codes/mcp --scope user

Then run /mcp, select qrx and sign in. Or commit this to a project's .mcp.json so the whole team gets it (each person signs in to their own account):

{
  "mcpServers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp"
    }
  }
}

With an API key instead (for example with claude -p or in CI):

claude mcp add --transport http qrx https://qrx.codes/mcp \
  --header "Authorization: Bearer $QRX_API_KEY" --scope user

A configured Authorization header replaces sign-in; remove it to sign in instead.

Claude Desktop uses the same connector settings as claude.ai; you don't edit claude_desktop_config.json for a remote server.

1. Open Customize → Connectors, select + Add, then Add custom connector. On Team and Enterprise, an Owner adds it under Organization settings → Connectors first, and each member then selects Connect.
2. Name: QRX. URL: https://qrx.codes/mcp.
3. Authentication: Sign in now, then sign in to QRX when Claude asks.
4. Save, then turn QRX on in a chat from the connectors menu.

With an API key instead, choose No sign-in and add Authorization with the value Bearer qrx_live_… under Request headers (where your organisation has request headers). Authentication can't be changed after saving; remove the connector and add it again.

Free Claude plans can add one custom connector.

1. Open chatgpt.com/plugins on the web, select +, then Add custom MCP server.
2. Name: QRX. Server URL: https://qrx.codes/mcp.
3. Authentication: OAuth. Accept the risk warning and select Create as a plugin.
4. Sign in to QRX when ChatGPT asks.

ChatGPT's custom MCP servers don't take API keys. Workspace admins can restrict custom MCP servers on Business and Enterprise plans.

Use the Install in Cursor button above, or add this to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project):

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

Cursor opens a browser to sign in to QRX when it connects.

With an API key instead:

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer ${env:QRX_API_KEY}" }
    }
  }
}

Use the Install in VS Code button above, or add this to .vscode/mcp.json:

{
  "servers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp"
    }
  }
}

From a terminal:

code --add-mcp '{"name":"qrx","type":"http","url":"https://qrx.codes/mcp"}'

VS Code opens a browser to sign in to QRX when it connects.

With an API key instead (VS Code asks for it and stores it securely):

{
  "inputs": [
    {
      "type": "promptString",
      "id": "qrx-api-key",
      "description": "QRX API key (starts with qrx_)",
      "password": true
    }
  ],
  "servers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer ${input:qrx-api-key}" }
    }
  }
}

Edit mcp_config.json (macOS/Linux ~/.config/devin/mcp_config.json, Windows %APPDATA%\devin\mcp_config.json; older Windsurf installs use ~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "qrx": {
      "serverUrl": "https://qrx.codes/mcp"
    }
  }
}

Note the key is serverUrl, not url. Windsurf asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer ${env:QRX_API_KEY}" }.

Open MCP Servers → Configure MCP Servers and add to cline_mcp_settings.json:

{
  "mcpServers": {
    "qrx": {
      "type": "streamableHttp",
      "url": "https://qrx.codes/mcp",
      "disabled": false,
      "autoApprove": ["list_styles", "get_qr_code", "list_qr_codes", "get_account", "get_profile"]
    }
  }
}

Cline asks you to sign in to QRX when it connects. In the Cline CLI, run cline mcp, choose qrx and Authorize OAuth. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }.

Add to settings.json:

{
  "context_servers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

Zed asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }; Zed then skips sign-in.

Run goose configure → Add Extension → Remote Extension (Streamable HTTP) and enter https://qrx.codes/mcp. Or edit config.yaml (macOS/Linux ~/.config/goose/config.yaml, Windows %APPDATA%\Block\goose\config\config.yaml):

extensions:
  qrx:
    name: qrx
    type: streamable_http
    enabled: true
    uri: https://qrx.codes/mcp
    timeout: 300

Goose opens your browser to sign in to QRX when it connects. With an API key instead, add the header Authorization: Bearer qrx_live_… (headers: in config.yaml).

codex mcp add qrx --url https://qrx.codes/mcp

Codex finds QRX's sign-in and opens your browser. Run codex mcp login qrx to sign in again later. The entry in ~/.codex/config.toml is just:

[mcp_servers.qrx]
url = "https://qrx.codes/mcp"

With an API key instead, add bearer_token_env_var = "QRX_API_KEY" to that entry.

gemini mcp add --transport http -s user qrx https://qrx.codes/mcp

Gemini CLI opens your browser to sign in to QRX when it connects; /mcp auth qrx signs in again later. Or in ~/.gemini/settings.json (note httpUrl, which selects Streamable HTTP):

{
  "mcpServers": {
    "qrx": {
      "httpUrl": "https://qrx.codes/mcp"
    }
  }
}

With an API key instead:

gemini mcp add --transport http -s user --header "Authorization: Bearer $QRX_API_KEY" qrx https://qrx.codes/mcp

In the Program tab, choose Install → Edit mcp.json and add:

{
  "mcpServers": {
    "qrx": {
      "url": "https://qrx.codes/mcp"
    }
  }
}

LM Studio asks you to sign in to QRX when it connects. With an API key instead, add "headers": { "Authorization": "Bearer qrx_live_…" }.

The skills/qrx folder follows the Agent Skills standard, so the same skill works in Codex, Gemini CLI, GitHub Copilot, Cursor, Goose and others. Install it with the cross-agent installer:

npx skills add qrxcodes/qrx-mcp

The skill expects the QRX MCP server to be connected (see your client above), or a QRX_API_KEY for the REST API.

gemini extensions install https://github.com/qrxcodes/qrx-mcp

Gemini CLI opens your browser to sign in to QRX when it connects; /mcp auth qrx signs in again later.

Clients that support MCP authorization need only https://qrx.codes/mcp: the server answers 401 until you sign in, so they ask when they connect. Otherwise point a Streamable HTTP client at the URL and send Authorization: Bearer qrx_… (or X-API-Key: qrx_…). Clients that only run local stdio servers can use @qrxcodes/mcp, which forwards to the same server with your API key:

{
  "mcpServers": {
    "qrx": {
      "command": "npx",
      "args": ["-y", "@qrxcodes/mcp"],
      "env": { "QRX_API_KEY": "qrx_live_…" }
    }
  }
}

Tools

Connecting needs sign-in or an API key. The tool list is public at https://qrx.codes/.well-known/mcp/server-card.json.

In clients that show interactive views (MCP Apps), such as Claude, the code also appears in a card that fills in when it is ready.

Example prompts

1. "Make a QR code for https://example.com/menu that looks like a watercolour street of cafés."
2. "Design a QR code for our wedding RSVP page, https://example.com/rsvp, as eucalyptus leaves and gold foil on cream paper."
3. "I need a QR code for a gig poster that opens https://example.com/tickets. Neon synthwave city at night."
4. "Show me the styles QRX has, then make a code for https://example.com in the one that best suits a bakery."
5. "List my QR codes from this week and give me the short links."
6. "The flyer code we printed last month should now open https://example.com/spring-sale instead."
7. "How many QR codes can I still make today?"
8. "Make three variations of a QR code for https://example.com/shop with a Japanese woodblock wave, and tell me which scans are verified."

How generation works

• generate_qr_code returns within a few seconds with an id and status: processing. The artwork usually takes under a minute on a GPU.
• get_qr_code then waits for up to 25 seconds per call (wait, 0–25). Agents call it again until the status is succeeded (or failed). In MCP Apps clients the card fills in with the image when it's ready.
• A finished code includes the image URL, the short link it encodes (shortUrl: https://qrx.to/<id> on qrx.codes) and the destination it redirects to. Every code is decoded before it's marked succeeded. A code's id and short link never change.
• Each code you start counts against your plan, even if you don't keep the result.

Plans and limits

A free account has a daily allowance of codes; a paid plan has more, and lets you re-point links. Current plans are at https://qrx.codes/upgrade.

The API, the MCP server and the website share one allowance. Each key is also rate limited (30 requests a minute and 6 new codes per 10 seconds). If you hit a limit the tool returns an error; get_account shows what is left and when the daily count resets. Limits: qrx.codes/developers.

What this repository contains

None of these files run code on your machine. They only point your client at https://qrx.codes/mcp.

Data and network use

Connecting to https://qrx.codes/mcp needs sign-in or an API key; without one the server answers 401. Clients send requests only to https://qrx.codes/mcp (and, when the skill falls back to the REST API, to https://qrx.codes/v1). Each request carries your sign-in token or API key and the prompt, destination link and style you asked for. Signing in goes through QRX's sign-in service at https://clerk.qrx.codes. A finished code's imageUrl is on https://qrx.codes/media/, which redirects to QRX's image CDN.

Privacy, terms and support

• Privacy: https://qrx.codes/privacy
• Terms: https://qrx.codes/terms
• Support: https://qrx.codes/developers or hello@qrx.codes
• API docs: qrx.codes/developers; MCP server: qrx.codes/developers/mcp; for agents: llms.txt and the OpenAPI document. No key needed to read them.

QRX stores the prompts, links and images you create so they appear in your account. It doesn't read your chat history; it only sees the arguments the client sends to its tools.

Licence

The configuration files, skill and documentation in this repository are released under the MIT licence. The QRX service itself is a hosted product, governed by the QRX terms.