Manage QR Codes via Scanova API

Scanova MCP Server

A Model Context Protocol (MCP) server for managing your Scanova QR code platform using the Scanova API. This server provides tools for QR code creation, design, and lifecycle management; folder organization; lead-capture forms and lead lists; analytics exports; and account user administration, through MCP-compatible IDEs like Cursor, VS Code, and Claude Desktop.

Features

• ✅ QR Codes: Create, list, retrieve, update, activate/deactivate, and delete QR codes; download them as PNG/JPG/PDF/SVG/EPS or as print-ready PDFs; and browse QR categories
• ✅ QR Design: Customize QR code visuals - patterns, eye shapes, frames, gradients, and error correction
• ✅ Folders: Create, list, update, and delete folders, and move or unassign QR codes between them
• ✅ Forms & Lead Capture: List, retrieve, update, and delete lead-capture forms and lead lists, and attach or detach either from a QR code
• ✅ Analytics: Pull account-level usage stats and per-QR performance metrics, and export analytics reports or raw scan logs
• ✅ Account Administration: List users and roles, invite or remove users, and update user role assignments
• ✅ Documentation Bridge: Query Scanova's docs via a live bridge to the Scanova docs MCP server

Prerequisites

• Scanova API key (get one from https://app.scanova.io/)
• MCP-compatible IDE (Cursor, VS Code, Claude Desktop, etc.)

Quick Setup

Step 1: Get Your Scanova API Key

1. Visit https://app.scanova.io/
2. Sign up or log in to your account
3. Navigate to API settings [https://app.scanova.io/settings/api] and generate your API key.

Step 2: Configure Your IDE

Add the following configuration to your IDE's MCP settings:

For Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http",
      "url": "https://mcp.scanova.io/mcp",
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

For VS Code (~/.vscode/mcp.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http", 
      "url": "https://mcp.scanova.io/mcp",
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

For Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "scanova-mcp": {
      "transport": "http",
      "url": "https://mcp.scanova.io/mcp", 
      "headers": {
        "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
      }
    }
  }
}

Tools

QR Code Management

QR Code Design

Folder Management

Forms & Lead Lists

Analytics

Account Administration

Documentation

Usage

The server provides the following MCP tools that you can use in your MCP-compatible IDE:

API Endpoints

The deployed server provides these endpoints:

• POST /mcp - Main MCP JSON-RPC endpoint
• GET /health - Health check endpoint
• GET / - Service information and documentation

Local Development (Optional)

If you want to run the server locally for development:

Installation

1. Clone the repository:

   git clone <repository-url>
   cd qcg-mcp
   

2. Install dependencies:

   uv sync
   

3. Run locally:

   # HTTP server mode
   uv run cloud_server.py
   
   # Or stdio mode for local MCP testing
   uv run main.py
   

4. Configure for local testing:

   {
     "mcpServers": {
       "qcg-mcp": {
         "transport": "http",
         "url": "http://localhost:8000/mcp",
         "headers": {
           "Authorization": "YOUR_SCANOVA_API_KEY_HERE"
         }
       }
     }
   }
   

Docker Deployment (Local)

1. Build the Docker image:

   docker build -t mcpserver:local .
   

2. Start the container:

   docker run -d --name mcpserver -p 8000:8000 mcpserver:local
   

   Or with Docker Compose:

   docker compose up -d
   

3. Verify the server is running:

   curl http://localhost:8000/health
   

4. Configure your IDE (HTTP transport):
   Use the "Configure for local testing" snippet above and point to http://localhost:8000/mcp, ensuring the Authorization header contains your Scanova API key.

5. View logs and stop:

   # View logs
   docker logs -f mcpserver
   
   # Stop and remove with Compose
   docker compose down
   
   # Or stop/remove single container
   docker stop mcpserver && docker rm mcpserver
   

Troubleshooting

Common Issues

1. "API key is required"

   • Ensure your Scanova API key is correctly set in the headers
   • Check that the header format matches one of the supported formats
   • Get your API key from https://app.scanova.io/

2. "Invalid token" error

   • Verify your API key is valid and active
   • Ensure there are no extra spaces or characters in the API key
   • Try regenerating your API key from the Scanova dashboard

3. Connection errors

   • Check that the server URL is correct
   • Ensure your internet connection is working
   • Verify the server is deployed and running

4. Tool not found

   • Restart your IDE after adding the MCP configuration
   • Check that the JSON configuration is valid
   • Verify the server responds at the /health endpoint