README.md•3.69 kB
# 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`):
```json
{
"mcpServers": {
"qrcode": {
"command": "npx",
"args": [
"scan-qrcode-mcp@latest"
]
}
}
}
```
Alternative using the global binary (after `npm i -g scan-qrcode-mcp`):
```json
{
"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:
```bash
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):
```bash
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:
```toml
[mcp_servers.qrcode]
command = "npx"
args = ["scan-qrcode-mcp@latest"]
```
or, if you installed globally:
```toml
[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