# 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/).
Raw data
{
"_id": null,
"home_page": null,
"name": "mcp-server-gelato",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": "Maksim Madzar <madzarmaksim@gmail.com>",
"keywords": "api, gelato, mcp, model-context-protocol, printing",
"author": null,
"author_email": "Maksim Madzar <madzarmaksim@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/09/d5/63afe417c4a0bf63ff2a450af3f488836ccdeec24fed0de151067fbf5e83/mcp_server_gelato-0.1.0.tar.gz",
"platform": null,
"description": "# Gelato MCP Server\n\nAn 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.\n\n## Features\n\n### \ud83d\udd27 Tools\n- **search_orders**: Advanced order search with multiple filters (status, country, date range, etc.)\n- **get_order_summary**: Retrieve specific order details\n- **search_products**: Search products in catalogs with filtering capabilities\n- **get_product**: Get detailed information about a specific product\n- **get_product_prices**: Get pricing information for products\n- **check_stock_availability**: Check stock availability across regions\n- **list_shipment_methods**: Get available shipment methods\n\n### \ud83d\udcda Resources \n- **orders://{order_id}**: Get detailed order information\n- **orders://recent**: Get the 10 most recent orders \n- **orders://drafts**: Get all draft orders\n- **catalogs://list**: List all available product catalogs\n- **catalogs://{catalog_uid}**: Get detailed catalog information\n- **catalogs://summary**: Quick overview of all catalogs\n\n## Prerequisites\n\n- Python 3.13+\n- Gelato API key (get one from [Gelato API Portal](https://developers.gelato.com/))\n\n## Installation\n\n### Quick Install with Claude Desktop\n\nThe easiest way to add this server to Claude Desktop:\n\n```bash\nclaude 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\n```\n\nReplace `your_gelato_api_key_here` with your actual Gelato API key from the [Gelato API Portal](https://developers.gelato.com/).\n\n**Alternative**: You can install without the API key and configure it later:\n```bash\nclaude mcp add gelato -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato\n```\nThen use the `configure_gelato` tool within Claude to set up your API key.\n\n### Manual Installation\n\n#### Option 1: Install from GitHub (Recommended)\n```bash\n# Install directly from GitHub\nuvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato\n\n# Or use uv tool install\nuv tool install git+https://github.com/madzarmaksim/mcp-server-gelato\n```\n\n#### Option 2: Local Development\n1. Clone this repository:\n ```bash\n git clone https://github.com/madzarmaksim/mcp-server-gelato.git\n cd mcp-server-gelato\n ```\n\n2. Install dependencies:\n ```bash\n uv install\n # or\n pip install -e .\n ```\n\n3. Set up your API key:\n ```bash\n cp .env.example .env\n # Edit .env and add your GELATO_API_KEY\n ```\n\n## Configuration\n\nCreate a `.env` file in the project root with your Gelato API key:\n\n```env\nGELATO_API_KEY=your_gelato_api_key_here\n\n# Optional configuration\n# GELATO_BASE_URL=https://order.gelatoapis.com\n# GELATO_PRODUCT_URL=https://product.gelatoapis.com\n# TIMEOUT=30\n# MAX_RETRIES=3\n# DEBUG=false\n```\n\n## Usage\n\n### Running the Server\n\n#### After installation via uvx:\n```bash\n# Run the server directly\nmcp-server-gelato\n\n# Or with environment variables\nGELATO_API_KEY=your_key_here mcp-server-gelato\n```\n\n#### Local development:\n```bash\n# Direct execution\npython main.py\n\n# Development mode with inspector\nuv run mcp dev main.py\n\n# Install in Claude Desktop from local directory\nuv run mcp install . --name \"Gelato API\"\n```\n\n### Using the Tools and Resources\n\n#### Search Orders\n```python\n# Search for draft orders\nsearch_orders(order_types=[\"draft\"])\n\n# Search US orders from last month\nsearch_orders(\n countries=[\"US\"], \n start_date=\"2024-01-01T00:00:00Z\",\n end_date=\"2024-01-31T23:59:59Z\"\n)\n\n# Search by customer name\nsearch_orders(search_text=\"John Smith\", limit=10)\n```\n\n#### Get Order Details\nUse the resource URI format to load order context:\n```\norders://37365096-6628-4538-a9c2-fbf9892deb85\n```\n\nOr use the tool:\n```python\nget_order_summary(order_id=\"37365096-6628-4538-a9c2-fbf9892deb85\")\n```\n\n#### Explore Product Catalogs\n```\ncatalogs://list # List all catalogs\ncatalogs://posters # Get poster catalog details\ncatalogs://summary # Quick overview\n```\n\n### Available Search Filters\n\nThe `search_orders` tool supports extensive filtering:\n\n- **order_types**: `[\"order\", \"draft\"]` - Filter by order type\n- **countries**: `[\"US\", \"DE\", \"CA\"]` - Filter by shipping country \n- **currencies**: `[\"USD\", \"EUR\", \"GBP\"]` - Filter by currency\n- **financial_statuses**: Payment statuses (`\"draft\"`, `\"paid\"`, `\"canceled\"`, etc.)\n- **fulfillment_statuses**: Fulfillment statuses (`\"created\"`, `\"printed\"`, `\"shipped\"`, etc.)\n- **search_text**: Search in customer names and order reference IDs\n- **start_date/end_date**: Date range filtering (ISO 8601 format)\n- **channels**: `[\"api\", \"shopify\", \"etsy\", \"ui\"]` - Filter by order channel\n- **limit/offset**: Pagination control (max 100 results per request)\n\n## Architecture\n\nThe server follows a modular architecture:\n\n```\nsrc/\n\u001c\\x00\\x00 client/\n\u0002 \u0014\\x00\\x00 gelato_client.py # HTTP client for Gelato API\n\u001c\\x00\\x00 models/\n\u0002 \u001c\\x00\\x00 common.py # Shared data models\n\u0002 \u001c\\x00\\x00 orders.py # Order-related models\n\u0002 \u0014\\x00\\x00 products.py # Product catalog models\n\u001c\\x00\\x00 resources/\n\u0002 \u001c\\x00\\x00 orders.py # Order resources (data exposure)\n\u0002 \u0014\\x00\\x00 products.py # Product catalog resources\n\u001c\\x00\\x00 tools/\n\u0002 \u0014\\x00\\x00 orders.py # Order tools (operations)\n\u001c\\x00\\x00 utils/\n\u0002 \u001c\\x00\\x00 auth.py # Authentication helpers\n\u0002 \u0014\\x00\\x00 exceptions.py # Custom exception classes\n\u001c\\x00\\x00 config.py # Configuration management\n\u0014\\x00\\x00 server.py # Main server setup\n```\n\n### Key Design Features\n\n- **Type Safety**: Full Pydantic models for all API interactions\n- **Error Handling**: Comprehensive error handling with custom exceptions\n- **Async Support**: All API calls are async for better performance \n- **Resource vs Tools**: Clear separation between data exposure (resources) and operations (tools)\n- **Extensible**: Easy to add new endpoints by following established patterns\n\n## Error Handling\n\nThe server includes robust error handling for common scenarios:\n\n- **Authentication errors**: Invalid or missing API keys\n- **Rate limiting**: Automatic retry with exponential backoff \n- **Network errors**: Timeout and connection error handling\n- **API errors**: Proper handling of Gelato API error responses\n- **Validation errors**: Request/response data validation\n\n## Troubleshooting\n\n### \"Failed to reconnect to gelato\" Error\n\nThis error occurs when the server starts without a valid `GELATO_API_KEY`. Here are the solutions:\n\n**For Claude Desktop Installation:**\n```bash\n# Install with API key\nclaude mcp add gelato -v GELATO_API_KEY=your_actual_api_key -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato\n\n# Or install without API key and configure later\nclaude mcp add gelato -- uvx --from git+https://github.com/madzarmaksim/mcp-server-gelato mcp-server-gelato\n# Then use the configure_gelato tool in Claude\n```\n\n**For Local Development:**\n```bash\n# Set environment variable\nexport GELATO_API_KEY=your_api_key_here\npython main.py\n\n# Or create .env file\necho \"GELATO_API_KEY=your_api_key_here\" > .env\npython main.py\n```\n\n### Getting Your API Key\n\n1. Visit the [Gelato API Portal](https://developers.gelato.com/)\n2. Sign up or log in to your account\n3. Generate an API key from your dashboard\n4. Use the key in the installation command or environment variable\n\n### Common Issues\n\n- **Invalid API Key**: Double-check your API key is correct and active\n- **Network Issues**: Ensure internet connectivity and no firewall blocking\n- **Permission Issues**: Make sure your API key has the necessary permissions\n\n## Development\n\n### Adding New Features\n\n1. **New Tools**: Add to `src/tools/` and register in server\n2. **New Resources**: Add to `src/resources/` and register in server \n3. **New Models**: Add to `src/models/` with proper Pydantic validation\n4. **New API Endpoints**: Extend `GelatoClient` in `src/client/`\n\n### Testing\n\n```bash\n# Test connection with your API key\npython -c \"\nimport asyncio\nfrom src.config import get_settings\nfrom src.client.gelato_client import GelatoClient\n\nasync def test():\n settings = get_settings()\n async with GelatoClient(settings.gelato_api_key, settings) as client:\n catalogs = await client.list_catalogs()\n print(f'Found {len(catalogs)} catalogs')\n\nasyncio.run(test())\n\"\n```\n\n## Troubleshooting\n\n### Common Issues\n\n1. **API Key Error**: Make sure `GELATO_API_KEY` is set correctly in your environment\n2. **Connection Timeout**: Check your network connection and increase timeout in config\n3. **Rate Limiting**: The server automatically retries with backoff, but you may need to slow down requests\n\n### Debug Mode\n\nEnable debug logging:\n```bash\nDEBUG=true python main.py\n```\n\n## Contributing\n\n1. Follow the existing code structure and patterns\n2. Add proper error handling for new endpoints\n3. Include Pydantic models for data validation\n4. Document new features in this README\n\n## License\n\nThis project is licensed under the MIT License.\n\n## Support\n\nFor Gelato API issues, visit the [Gelato Help Center](https://help.gelato.com/).\nFor MCP-related issues, check the [MCP documentation](https://modelcontextprotocol.io/).",
"bugtrack_url": null,
"license": "MIT",
"summary": "MCP server for Gelato print-on-demand API",
"version": "0.1.0",
"project_urls": {
"Bug Tracker": "https://github.com/madzarmaksim/mcp-server-gelato/issues",
"Documentation": "https://github.com/madzarmaksim/mcp-server-gelato#readme",
"Homepage": "https://github.com/madzarmaksim/mcp-server-gelato",
"Repository": "https://github.com/madzarmaksim/mcp-server-gelato.git"
},
"split_keywords": [
"api",
" gelato",
" mcp",
" model-context-protocol",
" printing"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "8e5f4b8a398b1f4332ddfb186e1c9dffc350a73a58a1653b3450222d9d6e306b",
"md5": "fea3deb4e74940cf1b4d2b2b77eadf79",
"sha256": "90a661428a91fc2596ef8183297c7c713ac5f92842d75eaf171d3e2122ac49c8"
},
"downloads": -1,
"filename": "mcp_server_gelato-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fea3deb4e74940cf1b4d2b2b77eadf79",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 43980,
"upload_time": "2025-09-17T11:18:02",
"upload_time_iso_8601": "2025-09-17T11:18:02.974383Z",
"url": "https://files.pythonhosted.org/packages/8e/5f/4b8a398b1f4332ddfb186e1c9dffc350a73a58a1653b3450222d9d6e306b/mcp_server_gelato-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "09d563afe417c4a0bf63ff2a450af3f488836ccdeec24fed0de151067fbf5e83",
"md5": "53cbf2371fe01bc2a47eb86b0104c8e2",
"sha256": "55f03c034eeceb496d5847c266243d16b59aa193750877ec9cb715197b7b8310"
},
"downloads": -1,
"filename": "mcp_server_gelato-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "53cbf2371fe01bc2a47eb86b0104c8e2",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 90284,
"upload_time": "2025-09-17T11:18:04",
"upload_time_iso_8601": "2025-09-17T11:18:04.830660Z",
"url": "https://files.pythonhosted.org/packages/09/d5/63afe417c4a0bf63ff2a450af3f488836ccdeec24fed0de151067fbf5e83/mcp_server_gelato-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-17 11:18:04",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "madzarmaksim",
"github_project": "mcp-server-gelato",
"github_not_found": true,
"lcname": "mcp-server-gelato"
}
JSON
