URL2QR-MCP by guangxiangdebizi - MCP Server

🔗 URL2QR MCP Server

A powerful MCP (Model Context Protocol) server that converts URLs into QR codes with downloadable links. Built with Express and TypeScript, providing seamless integration with AI assistants like Claude.

✨ Features

🔗 URL to QR Code Conversion - Transform any URL into a scannable QR code
📥 Downloadable Links - Get HTTP download links for generated QR codes
⚙️ Customizable Options - Control error correction level and image size
🚀 Streamable HTTP - Modern MCP transport protocol support
🌍 Remote Service Available - Use our hosted service at http://47.79.147.241:3055/mcp
🔌 Easy Integration - Works with Claude Desktop and other MCP clients
🎨 Clean API - RESTful endpoints for health checks and file serving

📦 Installation

Installing via Smithery

To install URL2QR automatically via Smithery:

npx -y @smithery/cli install @guangxiangdebizi/url2qr-mcp

Via npm (Global)

npm install -g @xingyuchen/url2qr-mcp

Via npm (Local Project)

npm install @xingyuchen/url2qr-mcp

From Source

git clone https://github.com/guangxiangdebizi/URL2QR-MCP.git
cd URL2QR-MCP
npm install
npm run build

🚀 Quick Start

Option 1: Use Remote Service (Recommended for Quick Testing) 🌍

No installation needed! We provide a hosted service for immediate use:

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "url2qr": {
      "type": "streamableHttp",
      "url": "http://47.79.147.241:3055/mcp",
      "timeout": 600
    }
  }
}

✨ That's it! You can now use the QR code generation tool without running your own server.

Tip: When self-hosting on a public server, remember to set the PUBLIC_BASE_URL environment variable so that generated download links use your public domain instead of localhost.

Option 2: Run Your Own Local Server

1. Start the Server

# If installed globally
url2qr-mcp

# If installed locally or from source
npm start

# For development
npm run dev

The server will start on http://localhost:3000 by default.

2. Configure MCP Client

Add to your MCP client configuration (e.g., Claude Desktop's claude_desktop_config.json):

{
  "mcpServers": {
    "url2qr": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}

3. Use the Tool

In Claude Desktop or any MCP-compatible client:

Convert https://github.com to a QR code

The AI will use the url_to_qrcode tool and provide you with a download link!

🔧 API Reference

Tool: `url_to_qrcode`

Converts a URL into a QR code image.

Parameters:

Parameter	Type	Required	Default	Description
`url`	string	✅ Yes	-	The URL to convert into a QR code
`errorCorrectionLevel`	string	❌ No	"M"	Error correction level: "L" (7%), "M" (15%), "Q" (25%), "H" (30%)
`width`	number	❌ No	300	Width of the QR code image in pixels

Example Response:

✅ QR Code Generated Successfully

Original URL: https://github.com

Download Link: http://localhost:3000/qrcodes/qr-abc123.png

QR Code Details:
- Filename: qr-abc123.png
- Size: 300x300px
- Error Correction: M

🌐 HTTP Endpoints

`GET /`

API information and documentation.

`GET /health`

Health check endpoint.

Response:

{
  "status": "healthy",
  "transport": "streamable-http",
  "activeSessions": 2,
  "serverName": "URL2QR-MCP",
  "version": "1.0.0"
}

`POST /mcp`

MCP protocol endpoint (JSON-RPC).

`GET /qrcodes/:filename`

Download generated QR code images.

⚙️ Configuration

Create a .env file in the project root:

PORT=3000
QR_OUTPUT_DIR=./qrcodes
# PUBLIC_BASE_URL is optional - auto-detected from request headers by default
PUBLIC_BASE_URL=http://localhost:3000

Environment Variables:

PORT - Server port (default: 3000)
QR_OUTPUT_DIR - Directory for storing QR code images (default: ./qrcodes)
PUBLIC_BASE_URL - Optional. External base URL for download links. If not set, the server automatically detects the URL from incoming request headers (supports reverse proxies with X-Forwarded-Host and X-Forwarded-Proto)

🎯 Auto-Detection Feature

The server automatically detects its public URL from incoming HTTP requests, so you don't need to configure PUBLIC_BASE_URL in most cases:

✅ Smithery/Cloud Deployments: Automatically uses the correct public domain
✅ Behind Reverse Proxy: Reads X-Forwarded-Host and X-Forwarded-Proto headers
✅ Local Development: Falls back to localhost:PORT

Only set PUBLIC_BASE_URL if you need to override the auto-detected value.

🏗️ Project Structure

URL2QR-MCP/
├── src/
│   ├── index.ts              # MCP server entry point
│   └── tools/
│       └── url2qr.ts         # QR code generation tool
├── qrcodes/                  # Generated QR codes (auto-created)
├── build/                    # Compiled JavaScript (auto-generated)
├── package.json
├── tsconfig.json
├── .env                      # Configuration
└── README.md

🔒 Session Management

The server implements automatic session cleanup:

Sessions expire after 30 minutes of inactivity
Cleanup runs every 15 minutes
Session IDs are managed via Mcp-Session-Id headers

🌐 Deployment Options

Remote Service (Production)

We provide a hosted service at:

Endpoint: http://47.79.147.241:3055/mcp
Health Check: http://47.79.147.241:3055/health
Status: 🟢 Online and ready to use

This is perfect for:

Quick testing without setup
Production use without infrastructure
Teams sharing a single endpoint

Local Deployment

Run your own instance for:

Development and testing
Private/isolated environments
Custom configurations
On-premise requirements

The server automatically detects its public URL from request headers, so it works seamlessly behind reverse proxies and in cloud environments without manual configuration.

Deploy on Smithery (Managed Hosting)

You can deploy URL2QR MCP server to Smithery for managed hosting:

Ensure the repository contains Dockerfile and smithery.yaml (already included)
Install the Smithery CLI locally:
```
npm install
npx smithery build
```
Push your code to GitHub and connect the repo in Smithery dashboard
Configure environment variables in Smithery (optional):
- PORT=3000
- QR_OUTPUT_DIR=/app/qrcodes
- PUBLIC_BASE_URL - Not required (auto-detected from requests)
Trigger a deployment from Smithery UI

✨ No manual URL configuration needed! The server automatically detects Smithery's public URL from request headers.

Refer to Smithery docs for more details: TypeScript Deployments, Project Configuration

📝 Examples

Basic Usage

// Tool parameters
{
  "url": "https://example.com"
}

Custom Error Correction

{
  "url": "https://example.com",
  "errorCorrectionLevel": "H"  // High error correction (30%)
}

Custom Size

{
  "url": "https://example.com",
  "width": 500  // 500x500 pixels
}

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the file for details.

👤 Author

Xingyu Chen

🙏 Acknowledgments

Built with Model Context Protocol SDK
QR code generation powered by qrcode
Express.js for HTTP server

📚 Resources

⭐ If you find this project useful, please consider giving it a star on GitHub!