Skulabs MCP Server

# Skulabs MCP Server A Model Context Protocol (MCP) server that exposes Skulabs API functionality as tools for AI agents like Claude, Retell AI voice agents, and other MCP-compatible applications. ## Features ### Inventory Management - **Get Inventory**: Retrieve inventory items by SKU, location, or all items - **Update Inventory**: Update quantity for specific SKUs - **Location-based Inventory**: Get inventory filtered by location ### Product Management - **Get Products**: Retrieve product information by SKU or all products - **Product Details**: Get detailed information about specific products - **Create Products**: Add new products to the system ### Order Management - **Get Orders**: Retrieve orders with optional status filtering - **Order Details**: Get detailed information about specific orders - **Create Orders**: Create new orders with customer and item information - **Update Order Status**: Change order status (pending, processing, shipped, delivered, cancelled) ### Customer Management - **Get Customers**: Retrieve customer information with optional email filtering - **Customer Details**: Get detailed information about specific customers - **Create Customers**: Add new customers to the system ### Analytics - **Sales Summary**: Get sales data for date ranges - **Inventory Summary**: Get inventory statistics and summaries ## Quick Start ### Prerequisites - Python 3.11+ - Skulabs API key - Railway account (for deployment) or local development setup ### Local Development 1. **Clone and setup**: ```bash git clone <repository> cd skulabs-mcp pip install -r requirements.txt ``` 2. **Configure environment**: ```bash cp env.example .env # Edit .env with your Skulabs API key ``` 3. **Run the server**: ```bash python skulabs_mcp_server.py ``` ### Railway Deployment 1. **Connect to Railway**: - Push your code to GitHub - Connect Railway to your GitHub repository - Railway will auto-detect Python and install dependencies 2. **Set Environment Variables**: - Go to Railway dashboard → Variables - Add `SKULABS_API_KEY` with your Skulabs API key - Optionally set `SKULABS_BASE_URL` (defaults to https://api.skulabs.com) 3. **Deploy**: - Railway will automatically deploy on git push - Get your server URL from Railway dashboard ## Configuration ### Environment Variables | Variable | Description | Default | Required | |----------|-------------|---------|----------| | `SKULABS_API_KEY` | Your Skulabs API key | - | Yes | | `SKULABS_BASE_URL` | Skulabs API base URL | https://api.skulabs.com | No | | `MCP_SERVER_NAME` | Server name for MCP | skulabs-mcp | No | | `MCP_SERVER_VERSION` | Server version | 1.0.0 | No | | `LOG_LEVEL` | Logging level | INFO | No | ### Getting Your Skulabs API Key 1. Log into your Skulabs account 2. Go to Settings → Advanced → API 3. Generate a new API key 4. Copy the key to your environment variables ## Usage with AI Agents ### Retell AI Integration 1. **In Retell AI Dashboard**: - Go to your voice agent configuration - Add MCP server connection - Use your Railway URL as the MCP server endpoint 2. **Voice Agent Prompts**: ``` You have access to Skulabs inventory and order management tools. You can check inventory, create orders, update order status, and manage customers. Use the available tools to help customers with their requests. ``` ### Claude Desktop Integration 1. **Add to Claude Desktop config**: ```json { "mcpServers": { "skulabs": { "command": "python", "args": ["/path/to/skulabs_mcp_server.py"], "env": { "SKULABS_API_KEY": "your-api-key" } } } } ``` ## API Reference ### Tool: get_inventory Retrieve inventory items with optional filtering. **Parameters**: - `sku` (string, optional): Specific SKU to retrieve - `location` (string, optional): Filter by location - `limit` (integer, optional): Max items to return (default: 100) - `offset` (integer, optional): Items to skip (default: 0) ### Tool: update_inventory Update inventory quantity for a specific SKU. **Parameters**: - `sku` (string, required): SKU to update - `quantity` (integer, required): New quantity - `location` (string, optional): Location to update ### Tool: get_orders Retrieve orders with optional status filtering. **Parameters**: - `status` (string, optional): Filter by status - `limit` (integer, optional): Max orders to return (default: 100) - `offset` (integer, optional): Orders to skip (default: 0) ### Tool: create_order Create a new order. **Parameters**: - `customer_id` (string, required): Customer ID - `items` (array, required): Order items with SKU, quantity, price - `shipping_address` (object, optional): Shipping address - `notes` (string, optional): Order notes [See full API documentation in the source code for all available tools] ## Error Handling The server includes comprehensive error handling: - **API Errors**: Skulabs API errors are caught and returned with details - **Validation Errors**: Input validation with clear error messages - **Network Errors**: Timeout and connection error handling - **Logging**: Structured logging for debugging and monitoring ## Development ### Project Structure ``` skulabs-mcp/ ├── skulabs_mcp_server.py # Main MCP server ├── skulabs_client.py # Skulabs API client ├── requirements.txt # Python dependencies ├── railway.json # Railway deployment config ├── Procfile # Process configuration ├── runtime.txt # Python version ├── env.example # Environment template └── README.md # This file ``` ### Adding New Tools 1. **Add method to SkulabsClient**: ```python async def new_method(self, param: str) -> Dict[str, Any]: return await self._make_request("GET", f"/endpoint/{param}") ``` 2. **Add tool definition in list_tools()**: ```python Tool( name="new_tool", description="Description of the tool", inputSchema={...} ) ``` 3. **Add handler in execute_tool()**: ```python elif name == "new_tool": return await client.new_method(arguments["param"]) ``` ## Support - **Skulabs API Support**: Email api-support@skulabs.com with "API Support" in subject - **MCP Protocol**: [Model Context Protocol Documentation](https://modelcontextprotocol.io) - **Issues**: Create GitHub issues for bugs or feature requests ## License MIT License - see LICENSE file for details.