mcp-server-gelato by madzarm - MCP Server

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 --env GELATO_API_KEY="your_gelato_api_key_here" -- uvx 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 mcp-server-gelato

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

Manual Installation

Option 1: Install from PyPI (Recommended)

# Install the package
uv install mcp-server-gelato
# or
pip install mcp-server-gelato

# Run the server
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or install as a tool
uv tool install mcp-server-gelato
GELATO_API_KEY="your_api_key_here" mcp-server-gelato

Option 2: Install from GitHub

# 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 3: Local Development

Clone this repository:

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

Install dependencies:
```
uv install
# or
pip install -e .
```

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)

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 (recommended)
claude mcp add gelato --env GELATO_API_KEY="your_actual_api_key" -- uvx mcp-server-gelato

# Or install without API key and configure later
claude mcp add gelato -- uvx mcp-server-gelato
# Then use the configure_gelato tool in Claude

For Local Development:

# Using PyPI package
GELATO_API_KEY="your_api_key_here" uvx mcp-server-gelato

# Or using local code
export GELATO_API_KEY=your_api_key_here
python main.py

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

Getting Your API Key

Visit the Gelato API Portal
Sign up or log in to your account
Generate an API key from your dashboard
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

New Tools: Add to src/tools/ and register in server
New Resources: Add to src/resources/ and register in server
New Models: Add to src/models/ with proper Pydantic validation
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

API Key Error: Make sure GELATO_API_KEY is set correctly in your environment
Connection Timeout: Check your network connection and increase timeout in config
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

Follow the existing code structure and patterns
Add proper error handling for new endpoints
Include Pydantic models for data validation
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.