Mcp Server Gelato

Gelato MCP 服务

用于与 Gelato 按需印刷 API 集成的 MCP（Model Context Protocol）服务。此服务提供工具和资源，可用于搜索订单、获取订单详情以及浏览产品目录。

功能

🔧 工具

• search_orders：使用多种筛选条件（状态、国家/地区、日期范围等）进行高级订单搜索
• get_order_summary：获取指定订单的详情
• search_products：在目录中搜索产品，并使用筛选功能
• get_product：获取指定产品的详细信息
• get_product_prices：获取产品定价信息
• check_stock_availability：检查各地区的库存情况
• list_shipment_methods：获取可用的配送方式

📚 资源

• orders://{order_id}：获取详细的订单信息
• orders://recent：获取最近的 10 个订单
• orders://drafts：获取所有草稿订单
• catalogs://list：列出所有可用的产品目录
• catalogs://{catalog_uid}：获取目录的详细信息
• catalogs://summary：快速查看所有目录概况

前提条件

• Python 3.13+
• Gelato API 密钥（从 Gelato API Portal 获取）

安装

使用 Claude Desktop 快速安装

将此服务添加到 Claude Desktop 的最简便方法：

claude mcp add gelato --env GELATO_API_KEY="your_gelato_api_key_here" -- uvx mcp-server-gelato

将 your_gelato_api_key_here 替换为你从 Gelato API Portal 获取的 Gelato API 密钥。

替代方案：你也可以不使用 API 密钥安装，之后再进行配置：

claude mcp add gelato -- uvx mcp-server-gelato

然后在 Claude 中使用 configure_gelato 工具设置 API 密钥。

手动安装

选项 1：从 PyPI 安装（推荐）

# 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

选项 2：从 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

选项 3：本地开发

1. 克隆此代码仓库：

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

2. 安装依赖项：

   uv install
   # or
   pip install -e .
   

3. 设置 API 密钥：

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

配置

在项目根目录中创建 .env 文件，并填入 Gelato API 密钥：

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

用法

运行服务

使用 uvx 安装后：

# Run the server directly
mcp-server-gelato

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

本地开发：

# 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"

使用工具和资源

搜索订单

# 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)

获取订单详情

使用资源 URI 格式加载订单上下文：

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

或者使用工具：

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

浏览产品目录

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

可用的搜索筛选条件

search_orders 工具支持丰富的筛选条件：

• order_types：["order", "draft"] - 按订单类型筛选
• countries：["US", "DE", "CA"] - 按配送国家/地区筛选
• currencies：["USD", "EUR", "GBP"] - 按货币筛选
• financial_statuses：付款状态（"draft"、"paid"、"canceled" 等）
• fulfillment_statuses：履行状态（"created"、"printed"、"shipped" 等）
• search_text：搜索客户姓名和订单参考 ID
• start_date/end_date：按日期范围筛选（ISO 8601 格式）
• channels：["api", "shopify", "etsy", "ui"] - 按订单渠道筛选
• limit/offset：分页控制（每次请求最多返回 100 条结果）

主要设计特性

• 类型安全：所有 API 交互均使用完整的 Pydantic 模型
• 错误处理：通过自定义异常进行全面的错误处理
• 异步支持：所有 API 调用均为异步，可提升性能
• 资源与工具：清晰区分数据提供（资源）和操作（工具）
• 可扩展性：遵循既定模式即可轻松添加新端点

错误处理

此服务针对常见情况提供了完善的错误处理：

• 身份验证错误：API 密钥无效或缺失
• 速率限制：自动重试，并采用指数退避策略
• 网络错误：处理超时和连接错误
• API 错误：妥善处理 Gelato API 错误响应
• 验证错误：验证请求和响应数据

故障排除

“Failed to reconnect to gelato” 错误

当服务器启动时未设置有效的 GELATO_API_KEY，就会出现此错误。解决方法如下：

对于 Claude Desktop 安装：

# 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

对于本地开发：

# 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

获取 API 密钥

1. 访问 Gelato API 门户
2. 注册或登录你的账户
3. 在控制面板中生成 API 密钥
4. 在安装命令或环境变量中使用该密钥

常见问题

• API 密钥无效：仔细检查 API 密钥是否正确且有效
• 网络问题：确保网络连接正常，且没有防火墙阻止连接
• 权限问题：确保 API 密钥拥有必要的权限

开发

添加新功能

1. 新工具：添加到 src/tools/ 并在服务器中注册
2. 新资源：添加到 src/resources/ 并在服务器中注册
3. 新模型：添加到 src/models/，并进行适当的 Pydantic 验证
4. 新 API 端点：扩展 src/client/ 中的 GelatoClient

测试

# 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())
"

故障排除

常见问题

1. API 密钥错误：确保在环境中正确设置了 GELATO_API_KEY
2. 连接超时：检查网络连接，并在配置中增加超时时间
3. 速率限制：服务器会自动进行退避重试，但你可能需要降低请求频率

调试模式

启用调试日志：

DEBUG=true python main.py

贡献

1. 遵循现有的代码结构和模式
2. 为新端点添加适当的错误处理
3. 添加用于数据验证的 Pydantic 模型
4. 在此 README 中记录新功能

许可证

本项目采用 MIT 许可证。

支持

如有 Gelato API 相关问题，请访问 Gelato 帮助中心。 如有 MCP 相关问题，请查阅 MCP 文档。