qrx-mcp

# 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 the Starter plan. This repository connects QRX to Claude, Cursor, VS Code and other MCP clients (ChatGPT once sign-in ships) through the remote server at `https://qrx.codes/mcp`.

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_QRX-0098FF?logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=qrx&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22qrx-api-key%22%2C%22description%22%3A%22QRX%20API%20key%20%28starts%20with%20qrx_%29%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fqrx.codes%2Fmcp%22%2C%22headers%22%3A%7B%22Authorization%22%3A%22Bearer%20%24%7Binput%3Aqrx-api-key%7D%22%7D%7D)
[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=qrx&config=eyJ1cmwiOiJodHRwczovL3FyeC5jb2Rlcy9tY3AiLCJoZWFkZXJzIjp7IkF1dGhvcml6YXRpb24iOiJCZWFyZXIgJHtlbnY6UVJYX0FQSV9LRVl9In19)
[![Glama](https://glama.ai/mcp/connectors/codes.qrx/mcp/badges/score.svg)](https://glama.ai/mcp/connectors/codes.qrx/mcp)
[![Licence: MIT](https://img.shields.io/badge/licence-MIT-green)](LICENSE)

Listed in the [official MCP Registry](https://registry.modelcontextprotocol.io/) as `codes.qrx/mcp`.

<p align="center"><img src="assets/icon.png" width="280" alt="A QR code painted as a watercolour river with pine trees, made by QRX"></p>
<p align="center"><sub>The QRX logo is a QRX code. Point your phone at it.</sub></p>

## 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 (Starter plan).
- **Check your allowance:** see how many codes you have left today.

## Connection details

| | |
|---|---|
| Server URL | `https://qrx.codes/mcp` |
| Transport | Streamable HTTP (stateless) |
| Auth (now) | API key in a header: `Authorization: Bearer qrx_…` (preferred), or `X-API-Key: qrx_…` for clients that can't add the `Bearer ` prefix. If both are sent, `Authorization` wins |
| Auth (coming) | OAuth sign-in with your QRX account; clients that support MCP OAuth will need only the URL |
| Without auth | `tools/list` and `list_styles` work; every other tool asks you to connect an account |
| Docs | [qrx.codes/developers/mcp](https://qrx.codes/developers/mcp) (public: server URL, client set-up, tools, limits, privacy) |

## Get an API key

1. Sign in at [qrx.codes](https://qrx.codes) (free).
2. Open [qrx.codes/developers/keys](https://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:

   ```bash
   # macOS / Linux
   export QRX_API_KEY="qrx_live_…"
   ```

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

Revoke a key at any time from the same page.

## Install

<details open>
<summary><b>Claude Code</b></summary>

**Option A: plugin (MCP server plus the QRX skill)**

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

When you enable the plugin, Claude Code asks for your QRX API key and keeps it in your system's credential store. 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.

**Option B: MCP server only**

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

Or commit this to a project's `.mcp.json` so the whole team gets it (each person sets their own `QRX_API_KEY`):

```json
{
  "mcpServers": {
    "qrx": {
      "type": "http",
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer ${QRX_API_KEY}" }
    }
  }
}
```

**When OAuth is live:** `claude mcp add --transport http qrx https://qrx.codes/mcp`, then run `/mcp` and sign in.

</details>

<details>
<summary><b>Claude (claude.ai and Claude Desktop): custom connector</b></summary>

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.
2. Name: `QRX`. URL: `https://qrx.codes/mcp`.
3. Authentication:
   - **Now:** choose the fixed-credentials option and, under **Request headers**, add `Authorization` with the value `Bearer qrx_live_…`.
   - **When OAuth is live:** choose **Sign in when needed**; Claude shows a Connect button the first time you make a code.
4. Save, then turn QRX on in a chat from the connectors menu.

Free Claude plans can add one custom connector.

</details>

<details>
<summary><b>ChatGPT</b></summary>

ChatGPT's custom MCP servers take OAuth or no authentication, not API keys, so QRX in ChatGPT needs the OAuth release.

**When OAuth is live:**

1. Open [chatgpt.com/plugins](https://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. Ask for a QR code; ChatGPT asks you to sign in to QRX the first time.

Workspace admins can restrict custom MCP servers on Business and Enterprise plans.

</details>

<details>
<summary><b>Cursor</b></summary>

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

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

**When OAuth is live:** drop the `headers` block; Cursor prompts you to sign in.

</details>

<details>
<summary><b>VS Code (GitHub Copilot)</b></summary>

Use the **Install in VS Code** button above (it asks for your key and stores it securely), or add this to `.vscode/mcp.json`:

```json
{
  "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}" }
    }
  }
}
```

From a terminal:

```bash
code --add-mcp '{"name":"qrx","type":"http","url":"https://qrx.codes/mcp","headers":{"Authorization":"Bearer ${input:qrx-api-key}"},"inputs":[{"type":"promptString","id":"qrx-api-key","description":"QRX API key","password":true}]}'
```

**When OAuth is live:** `{"type": "http", "url": "https://qrx.codes/mcp"}` is enough.

</details>

<details>
<summary><b>Windsurf / Devin Desktop</b></summary>

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`):

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

Note the key is `serverUrl`, not `url`.

</details>

<details>
<summary><b>Cline</b></summary>

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

```json
{
  "mcpServers": {
    "qrx": {
      "type": "streamableHttp",
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer qrx_live_…" },
      "disabled": false,
      "autoApprove": ["list_styles", "get_qr_code", "list_qr_codes", "get_account", "get_profile"]
    }
  }
}
```

**When OAuth is live:** remove `headers` and use **Authorize OAuth** on the server.

</details>

<details>
<summary><b>Zed</b></summary>

Add to `settings.json`:

```json
{
  "context_servers": {
    "qrx": {
      "url": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer qrx_live_…" }
    }
  }
}
```

**When OAuth is live:** leave out `headers`; Zed runs the MCP sign-in flow when no `Authorization` header is set.

</details>

<details>
<summary><b>Goose</b></summary>

Run `goose configure` → **Add Extension** → **Remote Extension (Streamable HTTP)**, enter `https://qrx.codes/mcp`, and add the header `Authorization: Bearer qrx_live_…`. Or edit `config.yaml` (macOS/Linux `~/.config/goose/config.yaml`, Windows `%APPDATA%\Block\goose\config\config.yaml`):

```yaml
extensions:
  qrx:
    name: qrx
    type: streamable_http
    enabled: true
    uri: https://qrx.codes/mcp
    headers:
      Authorization: "Bearer qrx_live_…"
    timeout: 300
```

</details>

<details>
<summary><b>OpenAI Codex CLI</b></summary>

Add to `~/.codex/config.toml`:

```toml
[mcp_servers.qrx]
url = "https://qrx.codes/mcp"
bearer_token_env_var = "QRX_API_KEY"
```

**When OAuth is live:** `codex mcp add qrx --url https://qrx.codes/mcp`, then `codex mcp login qrx`.

</details>

<details>
<summary><b>Gemini CLI</b></summary>

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

Or in `~/.gemini/settings.json` (note `httpUrl`, which selects Streamable HTTP):

```json
{
  "mcpServers": {
    "qrx": {
      "httpUrl": "https://qrx.codes/mcp",
      "headers": { "Authorization": "Bearer $QRX_API_KEY" }
    }
  }
}
```

</detai