mcp-server-gelato 0.1.0
MCP server for Gelato print-on-demand API
License: MIT
Requires Python: >=3.11
Keywords: api, gelato, mcp, model-context-protocol, printing

# 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](https://developers.gelato.com/))

## Installation

### Quick Install with Claude Desktop

The easiest way to add this server to Claude Desktop:

```bash
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](https://developers.gelato.com/).

**Alternative**: You can install without the API key and configure it later:
```bash
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)
```bash
# 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:
   ```bash
   git clone https://github.com/madzarmaksim/mcp-server-gelato.git
   cd mcp-server-gelato
   ```

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

3. Set up your API key:
   ```bash
   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:

```env
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:
```bash
# Run the server directly
mcp-server-gelato

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

#### Local development:
```bash
# 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
```python
# 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:
```python
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:**
```bash
# 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:**
```bash
# 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](https://developers.gelato.com/)
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

```bash
# 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:
```bash
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](https://help.gelato.com/).
For MCP-related issues, check the [MCP documentation](https://modelcontextprotocol.io/).