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": []
    }
  }
}

<details> <summary>Claude Desktop</summary>

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

</details>

<details> <summary>Claude Code</summary>

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

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

</details>

<details> <summary>VS Code (GitHub Copilot with MCP)</summary>

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"]}'

</details>

<details> <summary>Codex CLI</summary>

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"

</details>

<details> <summary>Cursor</summary>

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

</details>

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