Overview

QRX paints a QR code into artwork from a description and a link, then decodes it before handing it over, so every code it returns scans. This package is a local stdio MCP server for clients that run servers as a command. It forwards everything to the hosted QRX MCP server at https://qrx.codes/mcp, so you get the same tools, schemas and interactive views. If your client can connect to a remote server by URL, you can skip this package and use https://qrx.codes/mcp directly. See qrx.codes/developers/mcp. Requires Node.js 18 or later. Listed in the official MCP Registry as codes.qrx/mcp. 1. Sign in at qrx.codes (free). 2. Create a key at qrx.codes/developers/keys. It starts with qrx_. 3. Give it to the server as the QRX_API_KEY environment variable, as in the examples below. Without a key the server still starts and clients can list the tools (from QRX's public server card, or a copy bundled with this package). Calling a tool returns an error asking you to set QRX_API_KEY.

README

QRX MCP server (stdio)

Art QR codes that always scan, from any MCP client.

QRX paints a QR code into artwork from a description and a link, then decodes it before handing it over, so every code it returns scans. This package is a local stdio MCP server for clients that run servers as a command. It forwards everything to the hosted QRX MCP server at https://qrx.codes/mcp, so you get the same tools, schemas and interactive views.

If your client can connect to a remote server by URL, you can skip this package and use https://qrx.codes/mcp directly. See qrx.codes/developers/mcp.

npx -y @qrxcodes/mcp

Requires Node.js 18 or later. Listed in the official MCP Registry as codes.qrx/mcp.

Get an API key

Sign in at qrx.codes (free).
Create a key at qrx.codes/developers/keys. It starts with qrx_.
Give it to the server as the QRX_API_KEY environment variable, as in the examples below.

Without a key the server still starts and clients can list the tools (from QRX’s public server card, or a copy bundled with this package). Calling a tool returns an error asking you to set QRX_API_KEY.

Install

Configuration

Variable	Default	Purpose
`QRX_API_KEY`	none	Your QRX API key, sent to the remote server as `Authorization: Bearer`
`QRX_MCP_URL`	`https://qrx.codes/mcp`	The remote server to forward to, for example a staging server
`QRX_MCP_SERVER_CARD_URL`	`/.well-known/mcp/server-card.json` on the `QRX_MCP_URL` origin	The public server card, used to list the tools when there is no valid key

Tools

Tool	What it does
`generate_qr_code`	Starts a new art QR code from a prompt and a link. Returns the code’s id straight away.
`get_qr_code`	Gets a code’s status, image and short link, waiting briefly while it is painted.
`list_qr_codes`	Lists your codes, newest first.
`change_qr_code_destination`	Points an existing code at a new link without reprinting it (on a paid plan).
`get_account`	Shows your plan and how many codes are left today.
`get_profile`	Shows which QRX account is connected.
`list_styles`	Lists the looks you can pass to `generate_qr_code`.

The tool list, input and output schemas and annotations come from the remote server at runtime, so they always match the hosted service. Clients that support MCP Apps also get the interactive code view (ui://qrx/code-v1.html).

Try: “Make a QR code for https://example.com/menu that looks like a watercolour street of cafés.”

How it works

The server speaks MCP over stdio to your client and over Streamable HTTP to https://qrx.codes/mcp. It forwards initialize (including your client’s capabilities), tool, resource and prompt requests, cancellations and progress notifications, and returns the remote’s results unchanged. If the connection to the remote drops, it reconnects on the next request and retries requests that can’t change anything; it never retries a tool that creates or changes a code.

It sends requests only to the configured URL. Each request carries your API key and the arguments your client passes to the tools. The server writes nothing to disk and logs only to stderr.

Development

npm install
npm test      # builds, then runs the tests against a local mock of the remote server

See RELEASING.md for publishing a new version.

Run your build against QRX with the MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector -e QRX_API_KEY=$QRX_API_KEY node dist/index.js

Links

MCP server docs: qrx.codes/developers/mcp
API docs: qrx.codes/developers
Remote server listing, plugins and skill: qrxcodes/qrx-mcp
Privacy: qrx.codes/privacy · Terms: qrx.codes/terms
Support and security reports: [email protected]

Licence

MIT. The QRX service itself is a hosted product, governed by the QRX terms.

View the full README on GitHub

Install

npx -y @qrxcodes/mcp

New to MCP? Start with the mcpskill.org guide →

Configuration

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