Free QR Code Generator MCP Server

A Model Context Protocol (MCP) server that provides QR code generation capabilities through AI assistants like Cursor, Claude, and other MCP-compatible clients.

Features

• 🎯 Multiple QR Code Types: URL, text, vCard, WiFi, email, phone
• 🎨 Customization Options: Size, colors, error correction levels
• 🚀 High Performance: Built with TypeScript and optimized for production
• 🔒 Secure: No local file system access, cloud-based API calls
• 📱 Cross-Platform: Works on Windows, macOS, and Linux

Installation

Global Installation (Recommended)

npm install -g freeqrcode-mcp-server

Local Installation

npm install freeqrcode-mcp-server

Usage

1. Cursor IDE Configuration

Add this to your cursor-mcp-config.json:

{
  "mcpServers": {
    "freeqrcode": {
      "command": "npx",
      "args": ["freeqrcode-mcp-server"],
      "env": {
        "QR_API_BASE_URL": "https://free-qr-code-generator.cc"
      }
    }
  }
}

2. VS Code Configuration

Add this to your VS Code settings:

{
  "mcp.servers": {
    "freeqrcode": {
      "command": "npx",
      "args": ["freeqrcode-mcp-server"],
      "env": {
        "QR_API_BASE_URL": "https://free-qr-code-generator.cc"
      }
    }
  }
}

3. Environment Variables

You can customize the API endpoint:

export QR_API_BASE_URL=https://your-custom-domain.com

Content Formats

The MCP server supports multiple content formats for different QR code types:

URL QR Codes

// Object format (recommended)
{
  type: 'url',
  content: { url: 'https://example.com' }
}

// String format (legacy)
{
  type: 'url',
  content: 'https://example.com'
}

Text QR Codes

{
  type: 'text',
  content: 'Hello, World!'
}

vCard QR Codes

{
  type: 'vcard',
  content: {
    firstName: 'John',
    lastName: 'Doe',
    email: '[email protected]',
    phone: '+1-555-123-4567'
  }
}

Email QR Codes

{
  type: 'email',
  content: {
    email: '[email protected]',
    subject: 'Hello',
    body: 'Message body'
  }
}

Phone QR Codes

{
  type: 'phone',
  content: { phone: '+1-555-123-4567' }
}

WiFi QR Codes

{
  type: 'wifi',
  content: {
    ssid: 'MyWiFi',
    password: 'password123',
    encryption: 'WPA',
    hidden: false
  }
}

Available Tools

1. Generate QR Code (Generic)

Generate any type of QR code with full customization options.

Parameters:

• type: Type of content (url, text, vcard, wifi, email, phone)
• content: Content to encode
• options: Customization options (size, colors, error correction)

Example:

// Generate a custom QR code
const qrCode = await mcp.callTool('generate_and_save_qr', {
  type: 'url',
  content: { url: 'https://free-qr-code-generator.cc' },
  filename: 'my-qr-code',
  options: {
    size: 512,
    foregroundColor: '#FF0000',
    backgroundColor: '#FFFFFF',
    errorCorrectionLevel: 'H'
  }
});

2. Generate URL QR Code

Quickly generate QR codes for URLs.

Parameters:

• content: Object with url field containing the URL to encode
• options: Customization options

Example:

const urlQR = await mcp.callTool('generate_and_save_qr', {
  type: 'url',
  content: {
    url: 'https://free-qr-code-generator.cc'
  },
  filename: 'my-url-qr',
  options: { size: 256 }
});

Alternative (using string content):

const urlQR = await mcp.callTool('generate_and_save_qr', {
  type: 'url',
  content: 'https://free-qr-code-generator.cc',
  filename: 'my-url-qr',
  options: { size: 256 }
});

3. Generate vCard QR Code

Create QR codes for contact information.

Parameters:

• name: Full name (required)
• email: Email address
• phone: Phone number
• company: Company name
• title: Job title
• address: Address
• website: Website URL
• options: Customization options

Example:

const vcardQR = await mcp.callTool('generate_vcard_qr', {
  name: 'John Doe',
  email: '[email protected]',
  phone: '+1-555-123-4567',
  company: 'Example Corp',
  title: 'Software Engineer',
  options: { size: 300 }
});

4. Generate WiFi QR Code

Create QR codes for WiFi network credentials.

Parameters:

• ssid: WiFi network name (required)
• password: WiFi password
• encryption: Encryption type (WPA, WEP, nopass)
• hidden: Whether the network is hidden
• options: Customization options

Example:

const wifiQR = await mcp.callTool('generate_wifi_qr', {
  ssid: 'MyWiFi',
  password: 'securepassword123',
  encryption: 'WPA',
  hidden: false,
  options: { size: 256 }
});

Customization Options

All QR code generation tools support these options:

• size: QR code size in pixels (64-1024, default: 256)
• foregroundColor: Foreground color in hex format (default: #000000)
• backgroundColor: Background color in hex format (default: #FFFFFF)
• errorCorrectionLevel: Error correction level (L, M, Q, H, default: M)

Error Correction Levels

• L (Low): 7% recovery capacity
• M (Medium): 15% recovery capacity (default)
• Q (Quartile): 25% recovery capacity
• H (High): 30% recovery capacity

API Endpoints

The MCP server communicates with the Free QR Code Generator API:

• Production: https://free-qr-code-generator.cc
• Custom: Set via QR_API_BASE_URL environment variable

Development

Building from Source

git clone https://github.com/yourusername/freeqrcode.git
cd freeqrcode/mcp-package
npm install
npm run build

Running in Development

npm run dev

Testing

npm test

Troubleshooting

Common Issues

1. MCP Server Not Starting

   • Ensure Node.js 18+ is installed
   • Check if the package is properly installed
   • Verify environment variables

2. API Connection Failed

   • Check internet connectivity
   • Verify API endpoint is accessible
   • Check CORS configuration

3. QR Generation Fails

   • Validate input parameters
   • Check API response for error details
   • Ensure content is not too long

Debug Mode

Set debug environment variable for verbose logging:

export DEBUG=freeqrcode-mcp:*

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Documentation: https://free-qr-code-generator.cc
• Issues: GitHub Issues
• Discussions: GitHub Discussions

Changelog

v1.0.0

• Initial release
• Support for URL, text, vCard, and WiFi QR codes
• Customization options (size, colors, error correction)
• MCP protocol compliance
• Cross-platform compatibility