Skip to main content
Glama
Endymionus

QR Reader MCP Server

by Endymionus
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

QR Reader MCP Server

视觉模型能看到图片里有二维码，但解不了码。这个 MCP 补上了这个缺口——让模型"看到即读到"。

Python License MCP

解决什么问题

视觉模型能识别出"图里有一个二维码"，但二维码解码走的是像素→二进制数据→文本的算法路径，模型做不到。这就导致一个很尴尬的场景：用户发来一张带二维码的截图，AI 只能说"我看到有个码"却读不出里面的内容。

QR Reader MCP Server 把二维码解码能力嵌入视觉模型的工作流——模型看到图片 → 调用 MCP 解码 → 拿到内容 → 继续处理。就像给模型装了一个二维码驱动。

两个工具

工具

说明

decode_qrcode_full

扫描整张图片，返回所有二维码的内容

enhance_and_decode

对模糊/反光/太小的区域做增强后再解码

比成功/失败更多的信息

实际场景中二维码质量参差不齐——模糊、反光、太小、对比度不够。MCP 在返回解码结果的同时，也附带了图像质量数据（模糊度、对比度、反光比例）和 result_code。Agent 拿到这些信息后，可以自然地告诉用户"这个码有点模糊，换个角度拍"或者"反光挡住了，调整一下光源"，而不需要用户自己猜测问题出在哪。

Related MCP server: QR Code Generator MCP

快速开始

前置依赖

Linux（Debian / Ubuntu）：

sudo apt install libzbar0

macOS：

brew install zbar

Windows：（三种方案，任选其一）

方案

说明

推荐

Docker

docker run -i --rm ghcr.io/<your-org>/qr-reader-mcp-server — 零配置，自带 zbar

⭐

预编译 DLL

从 zbar Windows builds 下载 libzbar-64.dll，放到 Python 安装目录或项目根目录

✅

vcpkg

vcpkg install zbar，然后设置 ZBAR_PATH 环境变量指向 vcpkg 的 bin 目录

备选

💡 如果 Windows 上 pip install pyzbar 后导入报错 ImportError，大概率是 zbar DLL 没找到。最省事的方式是用 Docker 运行。

安装运行

# 克隆
git clone https://github.com/Shalim-C/QR.git
cd QR

# 安装
pip install -e .

# 启动（stdio 模式）
python -m qr_reader.server

接入 MCP 客户端

Claude Desktop

编辑 claude_desktop_config.json：

{
  "mcpServers": {
    "qr-reader": {
      "command": "python",
      "args": ["-m", "qr_reader.server"],
      "env": {
        "LOG_LEVEL": "info",
        "READ_ONLY_MODE": "false"
      }
    }
  }
}

或使用 Docker：

{
  "mcpServers": {
    "qr-reader": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "ghcr.io/<your-org>/qr-reader-mcp-server"
      ]
    }
  }
}

VS Code / Cursor

Install in VS Code

点击上方按钮一键安装，或手动配置：

Ctrl + Shift + P → MCP: Open User Configuration，添加：

{
  "servers": {
    "qr-reader": {
      "command": "python",
      "args": ["-m", "qr_reader.server"],
      "env": {
        "LOG_LEVEL": "info",
        "READ_ONLY_MODE": "false"
      }
    }
  }
}

Continue.dev

编辑 ~/.continue/config.json：

{
  "experimental": {
    "mcpServers": {
      "qr-reader": {
        "command": "python",
        "args": ["-m", "qr_reader.server"],
        "env": {
          "LOG_LEVEL": "info"
        }
      }
    }
  }
}

Reasonix

编辑 config.toml，在 [[plugins]] 段追加：

[[plugins]]
name    = "qr-reader"
command = "python"
args    = ["-m", "qr_reader.server"]
env     = { LOG_LEVEL = "info", READ_ONLY_MODE = "false" }

Codex (OpenAI) / Zed / Cursor

这些客户端在 Web 控制台或设置面板中配置 MCP Server，搜索 "MCP Server" 选项，填入：

  • Command: python

  • Arguments: -m qr_reader.server

  • Environment: LOG_LEVEL=info

环境变量

变量

默认值

说明

LOG_LEVEL

info

日志级别：debug、info、warning、error

READ_ONLY_MODE

false

设为 true 禁用 enhance_and_decode（仅保留 decode_qrcode_full）

MAX_IMAGE_SIZE

10485760

图片大小上限（字节，默认 10 MB）

工具说明

decode_qrcode_full

对整张图片进行二维码识别和解码，返回结构化结果和质量指标。

输入参数：

参数

类型

必填

说明

image_base64

string

二选一

Base64 编码的图片

image_url

string

二选一

图片 URL

返回示例：

{
  "success": true,
  "result_code": "SUCCESS",
  "results": [
    {
      "content": "https://example.com",
      "bbox": [50, 60, 200, 200],
      "type": "QRCODE",
      "raw_bytes": "..."
    }
  ],
  "diagnosis": {
    "total_detected": 1,
    "quality": {
      "blur_score": 128.5,
      "contrast": 0.72,
      "glare_ratio": 0.05,
      "noise_level": 12.3
    }
  },
  "suggestion": null
}

enhance_and_decode

裁剪指定区域，执行增强操作后再解码。

输入参数：

参数

类型

必填

说明

image_base64

string

二选一

Base64 编码的图片

image_url

string

二选一

图片 URL

bbox

[int,int,int,int]

是

目标区域 [x, y, width, height]

operations

object[]

是

增强操作列表（见下方）

增强操作：

操作

说明

关键参数

upscale

放大区域

scale（默认 2.0）

sharpen

锐化边缘

strength（默认 1.5）

adjust_contrast

调整对比度

alpha（默认 1.5），beta（默认 0）

denoise

降噪

h（默认 10）

结果码说明

result_code 告诉 AI 助手下一步该做什么：

结果码

含义

AI 应该做什么

SUCCESS

解码成功

直接使用内容

SUCCESS_WITH_WARNING

解码成功但内容可能有异常

检查警告，验证内容

RETRYABLE

质量问题，可修复

调用 enhance_and_decode 重试

NO_QR_FOUND

未检测到二维码

告知用户图中没有二维码

QR_UNRECOVERABLE

二维码已损坏无法恢复

告知用户二维码损坏

示例对话

接入后试试对 AI 助手说：

  • "帮我读一下这张截图里的二维码"

  • "这个二维码太模糊了，试试增强后再读"

  • "扫描这张照片里的所有二维码，列出内容"

  • "这个收据上的码很难扫——能修复一下吗？"

只读模式

设置 READ_ONLY_MODE=true 后，仅保留 decode_qrcode_full 工具。此模式下 enhance_and_decode 不可用——AI 只能扫描，不能修改图片。

适用于审计/日志场景，确保行为确定、无副作用。

安全说明

  • 本服务只处理你提供的图片，不访问你的文件系统

  • image_url 仅用于获取你指定的图片，不做其他网络请求

  • stdio 模式下无需 API Key 或认证

  • 设置 MAX_IMAGE_SIZE 可限制内存占用

  • 日志不记录图片内容和解码数据

项目结构

qr-reader-mcp-server/
├── README.md
├── LICENSE
├── pyproject.toml
├── requirements.txt
├── .env.example
├── .gitignore
├── Dockerfile
├── docker-compose.yml
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
├── docs/
│   ├── setup.md
│   ├── tools.md
│   ├── troubleshooting.md
│   └── prompts.md
├── src/
│   └── qr_reader/
│       ├── __init__.py
│       ├── server.py          # MCP 入口
│       └── core/
│           ├── __init__.py
│           ├── decoder.py     # 二维码解码（基于 pyzbar）
│           ├── quality.py     # 图像质量分析
│           └── diagnosis.py   # 结果分类诊断
└── tests/
    ├── __init__.py
    ├── test_decoder.py
    ├── test_diagnosis.py
    └── test_quality.py

开发

本地运行与调试

git clone https://github.com/Shalim-C/QR.git
cd QR
pip install -e ".[dev]"

MCP Inspector 验证

使用 MCP Inspector 在浏览器中调试工具调用，无需配置客户端：

npx @modelcontextprotocol/inspector python -m qr_reader.server

浏览器打开后即可在 UI 中手动调用 decode_qrcode_full 和 enhance_and_decode，查看返回结果。

运行测试

pytest tests/ -v

CI 在 3 个 Python 版本（3.10 / 3.11 / 3.12）上运行测试 + Docker 镜像构建，详见 .github/workflows/ci.yml。

Docker 构建

docker build -t qr-reader-mcp-server .

开源协议

MIT — 详见 LICENSE。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessSyncing

Resources

Related MCP Connectors

Related MCP Servers