🔥 Hotline

MCP server for Shopify that lets merchants query their store data via AI (Claude, Cursor, etc).

Key differentiator: Metatooling - AI can create new query tools on the fly, save them, and share with the community.

🚀 Quick Start

For Merchants

1. Install the Hotline app from the Shopify App Store
2. Copy your MCP configuration from the Settings page
3. Add it to your AI assistant (Claude Desktop or Cursor)
4. Start asking questions about your store!

Example Prompts

"Show me my top 10 products by inventory"
"Find customers who haven't ordered in 90 days"
"Get all unfulfilled orders from the last week"
"Create a tool to find products low on stock"

🏗️ Architecture

┌─────────────────┐     ┌─────────────────┐     ┌─────────────┐
│ Cursor/Claude   │ MCP │ Hotline Server  │ GQL │ Shopify     │
│ (user's AI)     │────►│ (your infra)    │────►│ Admin API   │
└─────────────────┘     └─────────────────┘     └─────────────┘
                               │
                               ▼
                        ┌─────────────────┐
                        │ Database        │
                        │ - tokens        │
                        │ - tool configs  │
                        └─────────────────┘

🛠️ Core Tools

Built-in tools for common operations:

| Tool | Description | |------|-------------| | get_products | Search and list products with filters | | get_product | Get detailed product info by ID | | get_orders | Search and list orders | | get_order | Get detailed order info by ID | | get_customers | Search and list customers | | get_customer | Get detailed customer info | | get_inventory | Check inventory levels |

✨ Metatools

The magic of Hotline - create, share, and discover tools:

| Tool | Description | |------|-------------| | create_tool | Create a new reusable query tool | | list_my_tools | Show your created and installed tools | | search_tools | Browse community tool library | | install_tool | Install a community tool | | uninstall_tool | Remove an installed tool | | share_tool | Share your tool with the community |

Creating a Custom Tool

Ask your AI to create a tool:

"Create a tool called get_churning_customers that finds customers 
who have placed more than 3 orders but haven't ordered in 90 days"

The AI will call create_tool with:

{
  "name": "get_churning_customers",
  "description": "Find customers with 3+ orders who haven't ordered in 90 days",
  "resource": "customers",
  "filters": [
    { "field": "orders_count", "operator": "greater_than", "value": { "$param": "minOrders" } },
    { "field": "last_order_date", "operator": "older_than", "value": { "$param": "days" } }
  ],
  "parameters": {
    "minOrders": { "type": "number", "default": 3 },
    "days": { "type": "number", "default": 90 }
  }
}

📁 Project Structure

hotline/
├── app/                    # Remix app (Shopify embedded)
│   ├── routes/
│   │   ├── app._index.tsx  # Settings page (token + config)
│   │   ├── app.tools.tsx   # Tool library
│   │   └── auth.$.tsx      # OAuth callback
│   └── shopify.server.ts   # Shopify client setup
│
├── mcp/                    # MCP server
│   ├── server.ts           # MCP server entry
│   ├── tools/
│   │   ├── core/           # Built-in tools
│   │   └── meta/           # Metatools
│   ├── engine/
│   │   ├── executor.ts     # Runs tool configs
│   │   ├── validator.ts    # Validates definitions
│   │   └── query-builder.ts # Builds GraphQL
│   └── auth.ts             # Token validation
│
├── prisma/
│   └── schema.prisma       # Database schema
│
└── package.json

🔧 Development

Prerequisites

• Node.js 20+
• pnpm/npm/yarn
• Shopify Partner account

Setup

1. Clone the repository

2. Install dependencies:

   npm install

3. Create .env file:

   SHOPIFY_API_KEY=your_api_key
   SHOPIFY_API_SECRET=your_api_secret
   SCOPES=read_products,read_orders,read_customers,read_inventory
   SHOPIFY_APP_URL=https://your-app.fly.dev
   DATABASE_URL="file:./dev.db"

4. Initialize database:

   npm run db:generate
   npm run db:push

5. Start development:

   npm run dev

Testing MCP Server Locally

# Set test token
export HOTLINE_TOKEN=your_test_token

# Run MCP server
npm run dev:mcp

🚢 Deployment

Vercel (Recommended)

1. Push your code to GitHub

2. Import the repo in Vercel

3. Add environment variables in Vercel dashboard:

   DATABASE_URL=postgresql://[email protected]/neondb?sslmode=require
   SHOPIFY_API_KEY=your-client-id-from-partners
   SHOPIFY_API_SECRET=your-api-secret-from-partners
   SHOPIFY_APP_URL=https://your-app.vercel.app
   SCOPES=read_products,read_orders,read_customers,read_inventory

4. Deploy!

5. Update app URLs in Shopify Partners:

   • App URL: https://your-app.vercel.app
   • Redirect URL: https://your-app.vercel.app/auth/callback

Database

The app uses Neon PostgreSQL for serverless-friendly production deployments.

📄 License

MIT

🤝 Contributing

Contributions welcome! Please read our contributing guidelines first.

Built with ❤️ for Shopify merchants who want AI superpowers.