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

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.

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

Environment Variables:

PORT - Server port (default: 3000)
QR_OUTPUT_DIR - Directory for storing QR code images (default: ./qrcodes)

🏗️ 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

📝 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!