Scan QRCode MCP Server

MCP server that decodes QR codes from either a data URL (base64) or an HTTP(S) image URL and returns the decoded text.

Features

Two precise tools for decoding:
- decode_qrcode_data_url — accepts imageDataUrl
- decode_qrcode_image_url — accepts imageUrl
Decodes common image formats (PNG, JPEG, etc.).
Deterministic behavior with clear errors for invalid inputs.

Getting Started

Configure this MCP server in your client using either npx (recommended) or the global binary.

Standard config (recommended, uses npx):

{
  "mcpServers": {
    "qrcode": {
      "command": "npx",
      "args": [
        "scan-qrcode-mcp@latest"
      ]
    }
  }
}

Alternative using the global binary (after npm i -g scan-qrcode-mcp):

{
  "mcpServers": {
    "qrcode": {
      "command": "scan-qrcode-mcp",
      "args": []
    }
  }
}

Claude Desktop

Follow the MCP install guide: https://modelcontextprotocol.io/quickstart/user Use the Standard config JSON above (name it qrcode).

Claude Code

Use the Claude Code CLI to add the QR MCP server:

claude mcp add qrcode npx scan-qrcode-mcp@latest

VS Code (GitHub Copilot with MCP)

Follow: https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server Or install via VS Code CLI (npx example):

code --add-mcp '{"name":"qrcode","command":"npx","args":["scan-qrcode-mcp@latest"]}'

Codex CLI

Edit ~/.codex/config.toml and add one of the following:

[mcp_servers.qrcode]
command = "npx"
args = ["scan-qrcode-mcp@latest"]

or, if you installed globally:

[mcp_servers.qrcode]
command = "scan-qrcode-mcp"

Cursor

Settings -> MCP -> Add new MCP Server. Name: qrcode. Either use npx scan-qrcode-mcp@latest or the global binary.

Notes:

Requires Node.js 18.17+.
If using the global binary but scan-qrcode-mcp is not found, ensure your global npm bin is on PATH and restart the client.

Project Structure

src/
  server.ts
  services/
    qrcode-service.ts
  utils/
    data-url.ts
tests/
  services/
    qrcode.spec.ts

Scripts

npm i: Install dependencies.
npm run dev: Start MCP server in watch mode (stdio transport).
npm run build: Compile TypeScript to dist/.
npm start: Run compiled server from dist/.
npm test: Run unit tests with coverage (Vitest).
npm run lint / npm run format: Lint and format.

Usage

The server uses stdio transport and exposes two tools:

decode_qrcode_data_url
- Input: { imageDataUrl: string } — data:<mime>;base64,<data> URL for the QR image
decode_qrcode_image_url
- Input: { imageUrl: string } — http(s) URL to the QR image

Examples (pseudo-JSON-RPC over MCP):

Decode from data URL

{
  "method": "tools/call",
  "params": {
    "name": "decode_qrcode_data_url",
    "arguments": { "imageDataUrl": "data:image/png;base64,..." }
  }
}

Decode from image URL

{
  "method": "tools/call",
  "params": {
    "name": "decode_qrcode_image_url",
    "arguments": { "imageUrl": "https://example.com/qr.png" }
  }
}

Response text content contains the decoded string.

Configuration

Requires Node.js 18.17+ for built-in fetch.
No environment variables are required.

Security Notes

Only http(s) is allowed for imageUrl. Data URLs must be base64-encoded.
Do not pass untrusted remote URLs without appropriate allowlisting in your environment.

License

MIT