Gelato MCP Server

An MCP (Model Context Protocol) server for integrating with Gelato's print-on-demand API. This server provides tools and resources to search orders, retrieve order details, and explore product catalogs.

Features

🔧 Tools

• search_orders: Advanced order search with multiple filters (status, country, date range, etc.)
• get_order_summary: Retrieve specific order details
• search_products: Search products in catalogs with filtering capabilities
• get_product: Get detailed information about a specific product
• get_product_prices: Get pricing information for products
• check_stock_availability: Check stock availability across regions
• list_shipment_methods: Get available shipment methods

📚 Resources

• orders://{order_id}: Get detailed order information
• orders://recent: Get the 10 most recent orders
• orders://drafts: Get all draft orders
• catalogs://list: List all available product catalogs
• catalogs://{catalog_uid}: Get detailed catalog information
• catalogs://summary: Quick overview of all catalogs

Prerequisites

• Python 3.13+
• Gelato API key (get one from Gelato API Portal)

Installation

Quick Install with Claude Desktop

The easiest way to add this server to Claude Desktop:

claude mcp add gelato -v GELATO_API_KEY=your_gelato_api_key_here -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

Replace your_gelato_api_key_here with your actual Gelato API key from the Gelato API Portal.

Alternative: You can install without the API key and configure it later:

claude mcp add gelato -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

Then use the configure_gelato tool within Claude to set up your API key.

Manual Installation

Option 1: Install from GitHub (Recommended)

# Install directly from GitHub
uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

# Or use uv tool install
uv tool install git+https://github.com/madzarmaksim/mcp-server-gelato

Option 2: Local Development

1. Clone this repository:

   git clone https://github.com/madzarmaksim/mcp-server-gelato.git
   cd mcp-server-gelato
   

2. Install dependencies:

   uv install
   # or
   pip install -e .
   

3. Set up your API key:

   cp .env.example .env
   # Edit .env and add your GELATO_API_KEY
   

Configuration

Create a .env file in the project root with your Gelato API key:

GELATO_API_KEY=your_gelato_api_key_here

# Optional configuration
# GELATO_BASE_URL=https://order.gelatoapis.com
# GELATO_PRODUCT_URL=https://product.gelatoapis.com
# TIMEOUT=30
# MAX_RETRIES=3
# DEBUG=false

Usage

Running the Server

After installation via uvx:

# Run the server directly
mcp-server-gelato

# Or with environment variables
GELATO_API_KEY=your_key_here mcp-server-gelato

Local development:

# Direct execution
python main.py

# Development mode with inspector
uv run mcp dev main.py

# Install in Claude Desktop from local directory
uv run mcp install . --name "Gelato API"

Using the Tools and Resources

Search Orders

# Search for draft orders
search_orders(order_types=["draft"])

# Search US orders from last month
search_orders(
    countries=["US"], 
    start_date="2024-01-01T00:00:00Z",
    end_date="2024-01-31T23:59:59Z"
)

# Search by customer name
search_orders(search_text="John Smith", limit=10)

Get Order Details

Use the resource URI format to load order context:

orders://37365096-6628-4538-a9c2-fbf9892deb85

Or use the tool:

get_order_summary(order_id="37365096-6628-4538-a9c2-fbf9892deb85")

Explore Product Catalogs

catalogs://list          # List all catalogs
catalogs://posters       # Get poster catalog details
catalogs://summary       # Quick overview

Available Search Filters

The search_orders tool supports extensive filtering:

• order_types: ["order", "draft"] - Filter by order type
• countries: ["US", "DE", "CA"] - Filter by shipping country
• currencies: ["USD", "EUR", "GBP"] - Filter by currency
• financial_statuses: Payment statuses ("draft", "paid", "canceled", etc.)
• fulfillment_statuses: Fulfillment statuses ("created", "printed", "shipped", etc.)
• search_text: Search in customer names and order reference IDs
• start_date/end_date: Date range filtering (ISO 8601 format)
• channels: ["api", "shopify", "etsy", "ui"] - Filter by order channel
• limit/offset: Pagination control (max 100 results per request)

Architecture

The server follows a modular architecture:

src/
\x00\x00 client/
   \x00\x00 gelato_client.py    # HTTP client for Gelato API
\x00\x00 models/
   \x00\x00 common.py           # Shared data models
   \x00\x00 orders.py           # Order-related models
   \x00\x00 products.py         # Product catalog models
\x00\x00 resources/
   \x00\x00 orders.py           # Order resources (data exposure)
   \x00\x00 products.py         # Product catalog resources
\x00\x00 tools/
   \x00\x00 orders.py           # Order tools (operations)
\x00\x00 utils/
   \x00\x00 auth.py             # Authentication helpers
   \x00\x00 exceptions.py       # Custom exception classes
\x00\x00 config.py               # Configuration management
\x00\x00 server.py               # Main server setup

Key Design Features

• Type Safety: Full Pydantic models for all API interactions
• Error Handling: Comprehensive error handling with custom exceptions
• Async Support: All API calls are async for better performance
• Resource vs Tools: Clear separation between data exposure (resources) and operations (tools)
• Extensible: Easy to add new endpoints by following established patterns

Error Handling

The server includes robust error handling for common scenarios:

• Authentication errors: Invalid or missing API keys
• Rate limiting: Automatic retry with exponential backoff
• Network errors: Timeout and connection error handling
• API errors: Proper handling of Gelato API error responses
• Validation errors: Request/response data validation

Troubleshooting

"Failed to reconnect to gelato" Error

This error occurs when the server starts without a valid GELATO_API_KEY. Here are the solutions:

For Claude Desktop Installation:

# Install with API key
claude mcp add gelato -v GELATO_API_KEY=your_actual_api_key -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato

# Or install without API key and configure later
claude mcp add gelato -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato
# Then use the configure_gelato tool in Claude

For Local Development:

# Set environment variable
export GELATO_API_KEY=your_api_key_here
python main.py

# Or create .env file
echo "GELATO_API_KEY=your_api_key_here" > .env
python main.py

Getting Your API Key

1. Visit the Gelato API Portal
2. Sign up or log in to your account
3. Generate an API key from your dashboard
4. Use the key in the installation command or environment variable

Common Issues

• Invalid API Key: Double-check your API key is correct and active
• Network Issues: Ensure internet connectivity and no firewall blocking
• Permission Issues: Make sure your API key has the necessary permissions

Development

Adding New Features

1. New Tools: Add to src/tools/ and register in server
2. New Resources: Add to src/resources/ and register in server
3. New Models: Add to src/models/ with proper Pydantic validation
4. New API Endpoints: Extend GelatoClient in src/client/

Testing

# Test connection with your API key
python -c "
import asyncio
from src.config import get_settings
from src.client.gelato_client import GelatoClient

async def test():
    settings = get_settings()
    async with GelatoClient(settings.gelato_api_key, settings) as client:
        catalogs = await client.list_catalogs()
        print(f'Found {len(catalogs)} catalogs')

asyncio.run(test())
"

Troubleshooting

Common Issues

1. API Key Error: Make sure GELATO_API_KEY is set correctly in your environment
2. Connection Timeout: Check your network connection and increase timeout in config
3. Rate Limiting: The server automatically retries with backoff, but you may need to slow down requests

Debug Mode

Enable debug logging:

DEBUG=true python main.py

Contributing

1. Follow the existing code structure and patterns
2. Add proper error handling for new endpoints
3. Include Pydantic models for data validation
4. Document new features in this README

License

This project is licensed under the MIT License.

Support

For Gelato API issues, visit the Gelato Help Center. For MCP-related issues, check the MCP documentation.