QR Scanner MCP

A Model Context Protocol (MCP) server that provides QR code generation and scanning capabilities. Built with Python and optimized for performance, this server allows AI assistants to create and read QR codes seamlessly.

Features

• QR Code Generation: Create QR codes from any text data with customizable output paths

• QR Code Scanning: Extract text and data from QR code images with position information

• High Performance: Built with OpenCV and pyzbar for fast image processing

• MCP Compatible: Full integration with Claude and other MCP-compatible AI assistants

• Error Handling: Robust error handling for missing files, invalid images, and malformed data

• Multiple QR Codes: Support for scanning multiple QR codes in a single image

Related MCP server: freeqrcode-mcp-server

Installation

This project uses UV for fast Python package management.

Prerequisites

• Python 3.11 or higher

• UV package manager

Install UV

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Install Dependencies

# Clone the repository
git clone <repository-url>
cd qrscanner-mcp

# Install dependencies
uv sync

Usage

Running the MCP Server

# Start the MCP server
uv run python main.py

The server communicates via stdin/stdout following the MCP protocol.

Available Tools

1. Generate QR Code

Creates a QR code image from text data.

Parameters:

• data (string, required): The text data to encode in the QR code

• file_path (string, optional): Path where to save the QR code image (default: "qr_code.png")

Example:

{
  "name": "generate_qr_code",
  "arguments": {
    "data": "Hello, World!",
    "file_path": "hello_world_qr.png"
  }
}

2. Scan QR Code

Scans and decodes QR codes from an image file.

Parameters:

• image_path (string, required): Path to the image file containing QR codes

Returns:

• QR code data/text

• QR code type (e.g., "QRCODE")

• Bounding rectangle coordinates (x, y, width, height)

Example:

{
  "name": "scan_qr_code",
  "arguments": {
    "image_path": "qr_code.png"
  }
}

Sample Response:

{
  "type": "QRCODE",
  "data": "Hello, World!",
  "rect": {
    "x": 50,
    "y": 50,
    "width": 200,
    "height": 200
  }
}

Development

Project Structure

qrscanner-mcp/
├── main.py              # MCP server implementation
├── pyproject.toml       # Project configuration and dependencies
├── README.md            # This file
├── UV_REFERENCE.md      # UV package manager reference
├── tests/
│   └── test_main.py     # Test suite
├── qrcodes/             # Sample QR code images
│   ├── qr_code.png
│   ├── with_logo.png
│   └── ...
└── uv.lock             # Dependency lock file

Running Tests

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test
uv run pytest tests/test_main.py::test_generate_qr_code_tool

Code Quality

# Format code
uv run ruff format

# Lint code
uv run ruff check

# Type checking (if mypy is added)
uv run mypy main.py

Dependencies

• mcp: Model Context Protocol implementation

• qrcode: QR code generation

• pillow: Image processing library

• pyzbar: QR code and barcode decoding

• opencv-python: Computer vision and image processing

• pytest: Testing framework (dev dependency)

Configuration

pyproject.toml

The project is configured as an MCP server with the following key settings:

[project]
name = "qrscanner-mcp"
version = "0.1.0"
dependencies = [
    "mcp",
    "qrcode",
    "pillow",
    "pyzbar",
    "opencv-python",
]

[project.scripts]
qrscanner-mcp = "main:main"

Integration with Claude

To use this MCP server with Claude, add it to your Claude configuration:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "qrscanner-mcp": {
      "command": "uv",
      "args": ["run", "python", "/path/to/qrscanner-mcp/main.py"],
      "cwd": "/path/to/qrscanner-mcp"
    }
  }
}

Claude Code Configuration

The server can be used directly with Claude Code by running it as a subprocess and communicating via the MCP protocol.

Example Workflows

1. Create a QR Code for a URL

# Generate QR code for a website
result = await handle_call_tool("generate_qr_code", {
    "data": "https://github.com/astral-sh/uv",
    "file_path": "uv_website_qr.png"
})

2. Scan QR Codes from Camera Image

# Scan QR codes from a photo
result = await handle_call_tool("scan_qr_code", {
    "image_path": "camera_image.jpg"
})

3. Process Multiple QR Codes

The scanner automatically detects and processes multiple QR codes in a single image:

# Image with multiple QR codes
result = await handle_call_tool("scan_qr_code", {
    "image_path": "multiple_qr_codes.png"
})
# Returns array with all detected QR codes

Error Handling

The server provides comprehensive error handling:

• File Not Found: Clear error messages when image files don't exist

• Invalid Images: Graceful handling of corrupted or unsupported image formats

• No QR Codes: Informative response when no QR codes are detected

• Decoding Errors: Proper error reporting for malformed QR codes

Performance

• Fast Scanning: Optimized with OpenCV and pyzbar for quick QR code detection

• Memory Efficient: Minimal memory footprint using efficient image processing

• Batch Processing: Can handle multiple QR codes in a single operation

• UV Package Management: Ultra-fast dependency resolution and installation

Contributing

1. Fork the repository

2. Create a feature branch: git checkout -b feature-name

3. Make your changes

4. Run tests: uv run pytest

5. Commit your changes: git commit -am 'Add feature'

6. Push to the branch: git push origin feature-name

7. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• For UV package manager documentation, see UV_REFERENCE.md

• For MCP protocol documentation, visit MCP Documentation

• For issues and feature requests, please open a GitHub issue

Changelog

v0.1.0

• Initial release

• QR code generation and scanning capabilities

• MCP server implementation

• UV package management integration

• Comprehensive test suite