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:

   git clone <repository>
   cd skulabs-mcp
   pip install -r requirements.txt

2. Configure environment:

   cp env.example .env
   # Edit .env with your Skulabs API key

3. Run the server:

   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:

   {
     "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:

   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():

   Tool(
       name="new_tool",
       description="Description of the tool",
       inputSchema={...}
   )

3. Add handler in execute_tool():

   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
• Issues: Create GitHub issues for bugs or feature requests

License

MIT License - see LICENSE file for details.