Orshot MCP Server: Image Generation from Templates

Overview

Orshot MCP Server is a lightweight adapter that exposes image-generation templates to apps that support the Model Context Protocol (MCP), such as Claude, Cursor, or custom LLM-driven workflows. Instead of manually crafting images per request, clients can call the MCP server to select a pre-designed or AI-generated template and supply dynamic values (text, colors, assets). The server turns those inputs into an actionable instruction or direct API call to Orshot to produce the final image.

This approach centralizes template management and lets conversational agents or automation pipelines generate visuals on demand. It is useful when you want reproducible brand-compliant images, automated variations for A/B testing, or programmatic visual content in chat UI flows without embedding image generation logic into every client.

Features

• Exposes an MCP-compatible endpoint for image generation orchestrations
• Supports pre-built or AI-created templates with dynamic placeholders
• Returns structured MCP responses that instruct clients or trigger Orshot API calls
• Configurable backend and routing, suitable for Claude, Cursor, or custom MCP consumers
• Simple installation and run steps (Node.js / Docker compatible)
• Example templates and request/response patterns for quick integration

Installation / Configuration

Clone and install the server, then configure environment variables and run. Example steps (assumes Node.js):

# Clone the repository
git clone https://github.com/rishimohan/orshot-mcp-server.git
cd orshot-mcp-server

# Install dependencies
npm install

# Create .env with required variables
cat > .env <<EOF
PORT=3000
ORSHOT_API_KEY=your_orshot_api_key
ORSHOT_BASE_URL=https://api.orshot.example
MCP_PATH=/mcp    # optional: endpoint path for MCP requests
EOF

# Start the server
npm start

Docker (optional):

# Build
docker build -t orshot-mcp-server .

# Run container
docker run -d -p 3000:3000 \
  -e ORSHOT_API_KEY=your_orshot_api_key \
  -e ORSHOT_BASE_URL=https://api.orshot.example \
  orshot-mcp-server

Common environment variables

Check the repository README for any additional options and example env files.

Available Resources

The project bundles several helpful resources to speed integration:

• templates/ — sample templates with placeholders you can reuse and modify
• examples/ — example MCP request/response payloads and client snippets
• docs/ or README — guidance on mapping variables and supported template fields
• GitHub issues and PRs — community examples and usage notes

Browse the source and examples at https://github.com/rishimohan/orshot-mcp-server for up-to-date assets.

How the MCP Interaction Works (example)

Typical flow:

1. Client (LLM or app) POSTs an MCP request describing intent and context to the server endpoint (e.g., POST /mcp).
2. Server maps the request to a template and returns an MCP-compatible response that either:
   • provides an actionable instruction for the calling app to call Orshot, or
   • directly calls Orshot and returns the generated image URL / metadata.

Example request (simplified):

POST /mcp
{
  "app": "chat-assistant",
  "intent": "create_promo_card",
  "context": {
    "template": "promo-card-v1",
    "values": { "title": "Spring Sale", "subtitle": "Up to 50% off", "cta": "Shop Now" }
  }
}

Example response (server decides to instruct the client):

{
  "status": "ok",
  "action": "generate_image",
  "provider": "orshot",
  "payload": {
    "template": "promo-card-v1",
    "variables": { "title": "Spring Sale", "subtitle": "Up to 50% off", "cta": "Shop Now" }
  }
}

Or, if the server performs generation:

{
  "status": "ok",
  "image": {
    "url": "https://cdn.orshot.example/generated/abcd1234.png",
    "width": 1200,
    "height": 630
  }
}

Use Cases

• Marketing image generation: Automate social cards, email headers, and ad creatives by swapping text and images into verified templates.
  • Example: Generate 50 product announcement images by changing title, price, background color via a looped MCP call.
• Chat-based design assistants: Allow LLMs (Claude, Cursor) to request images mid-conversation and return assets inline.
  • Example: User asks “Create a banner for our spring collection”; the assistant invokes the MCP endpoint with template “banner-hero” and user-provided copy.
• Personalized assets for users: Produce avatars, profile banners, certificates, or badges with user-specific names and photos.
  • Example: Certificate template with placeholder {name}; MCP server returns a generated PDF/PNG with the given name filled.
• Rapid prototyping and A/B testing: Create multiple variations of a visual for experiments by modifying template variables programmatically.

Getting Help and Next Steps

• Repository: https://github.com/rishimohan/orshot-mcp-server — check examples and issues
• Review the templates folder to learn placeholder names and supported fields
• Integrate with your LLM or MCP-capable app by pointing the app’s tool/integration config to the MCP endpoint
• If you need synchronous generation, configure the server to call Orshot and return the final asset URL; otherwise instruct the client to perform the call

This server is intended as an integration layer: it standardizes how templates are exposed to LLM-driven experiences and helps teams generate consistent images from a central template catalog.