Repository avatar
AI Tools
v1.0.0
active

neoreader-qr

io.github.NeoReader/neoreader-qr

Create dynamic QR codes, change where they go and read scan stats from your AI assistant.

Documentation

QR Code Generator API and MCP Server for Dynamic QR Codes

This repository documents the NeoReader QR code generator API: a free dynamic QR code API that creates QR codes whose destination you can change after printing, and counts every scan without storing IP addresses. It also documents the NeoReader QR code MCP server, so you can use a QR code generator for Claude, ChatGPT, Cursor, VS Code and other AI assistants by asking in plain words.

The pages also live at https://neoreader.com/developers. This repository adds runnable examples in cURL, Node.js, Python and PHP, the OpenAPI description, and the entry for the official MCP registry.

QR Code API Free for Members

The API and the MCP server are free for every member while NeoReader Pro is being built. A member can hold up to 250 dynamic codes and make 120 requests a minute. Sign in at https://neoreader.com/login with Google or an emailed link. No card is needed.

Quick Start: Create a Dynamic QR Code with the API

  1. Sign in at neoreader.com, open Account, then API Tokens, and choose Create Token. Copy it. It is shown once.

  2. Keep it in an environment variable:

    export NEOREADER_TOKEN="your token"
    
  3. Create a code:

    curl -X POST "https://neoreader.com/api/v1/codes" \
      -H "Authorization: Bearer $NEOREADER_TOKEN" \
      -H "Accept: application/json" \
      -H "Content-Type: application/json" \
      -d '{"title":"Spring menu","destination":"https://example.com/menu"}'
    
    {
      "data": {
        "slug": "k7Xp2m",
        "short_url": "https://neoreader.com/q/k7Xp2m",
        "title": "Spring menu",
        "destination": "https://example.com/menu",
        "status": "active",
        "scans_count": 0
      }
    }
    
  4. Print short_url as a QR code. Change destination whenever you like with PATCH /codes/{slug}, and the printed code keeps working.

The API returns the short URL a dynamic code holds. It does not draw the image. Draw it yourself from short_url with any QR library (examples/node/create-and-render.mjs and examples/python/create_and_render.py show how), or style and download it in the NeoReader designer.

Dynamic QR Code API

A dynamic QR code holds a short link, neoreader.com/q/SLUG, that redirects to a destination you control. With the API you can:

  • create, list, read, update and delete codes;
  • change a destination without reprinting;
  • set a start date, an expiry, a scan limit, a password and UTM tags;
  • read scan statistics: totals, a daily series, countries, devices, operating systems and browsers.

Read more in docs/dynamic-qr-codes.md and docs/codes.md.

Bulk QR Code API

There is no special bulk endpoint, and none is needed. Loop over a spreadsheet and call POST /codes for each row. A member can make up to 120 requests a minute and hold up to 250 dynamic codes. docs/bulk-qr-codes.md explains the pattern, and every language has a ready script that reads a CSV file:

LanguageScript
cURL and jqexamples/curl/bulk-create-codes.sh
Node.jsexamples/node/bulk-create-codes.mjs
Pythonexamples/python/bulk_create_codes.py
PHPexamples/php/bulk_create_codes.php

QR Code MCP Server for AI Assistants

NeoReader runs a hosted Model Context Protocol server at:

https://neoreader.com/mcp

Add that address in your assistant, sign in to NeoReader, read what the assistant can and cannot do, and choose Allow. Sign-in is OAuth 2.1 with PKCE and dynamic client registration, so there is no key to copy. Clients that take a header, such as Cursor and VS Code, can send an API token instead.

ToolWhat it does
create_codeMakes a dynamic QR code from a title and a destination
list_codesFinds your codes by search word, folder or status
update_codeChanges the destination, title, folder, expiry or on/off state
get_code_statsReads scans by day, country, device, system and browser
pause_codeStops a code redirecting without deleting it
delete_codeDeletes a code for good, only when you ask

More in docs/mcp-server.md.

QR Code Generator for Claude, ChatGPT, Cursor and VS Code

AssistantGuide
Claudedocs/connector/claude.md
ChatGPTdocs/connector/chatgpt.md
Cursordocs/connector/cursor.md
VS Code and GitHub Copilotdocs/connector/vscode.md
Claude Codedocs/connector/claude-code.md

Things to ask once you are connected:

What Is Here

Folder or fileWhat it holds
docs/Quick start, authentication, codes, stats, errors and limits, dynamic QR codes, bulk QR codes, the MCP server, and a guide for each assistant
examples/Runnable scripts for every endpoint in cURL, Node.js, Python and PHP
openapi.jsonThe OpenAPI 3.1 description, the same file as https://neoreader.com/openapi.json
mcp/server.jsonThe entry for the official MCP registry: a remote server at https://neoreader.com/mcp with OAuth sign-in
CHANGELOG.mdWhat changed in the API and the connector, newest first

Keeping This Repository Current

The documentation and examples are written from the NeoReader source, so a fix to the generated files is applied there. To report a mistake, open an issue or a pull request and describe what is wrong. See CONTRIBUTING.md.

License

The documentation and examples are MIT licensed. See LICENSE. The NeoReader service itself is covered by its terms.

Topics

For whoever maintains the repository on GitHub, these are the suggested settings.

Description: QR code generator API and MCP server for dynamic QR codes: REST API docs, examples in cURL, Node.js, Python and PHP, and guides for Claude, ChatGPT, Cursor and VS Code.

Website: https://neoreader.com/developers

Topics: qr-code, qr-code-generator, qr-code-api, dynamic-qr-code, qr-code-generator-api, bulk-qr-code, mcp, mcp-server, model-context-protocol, claude, chatgpt, cursor, github-copilot, openapi, rest-api, api-documentation, oauth, ai-agents

No installation packages available.

Remote