Shopify Liquid MCP Server

🚀 Fast, local, offline-first MCP server for Shopify Liquid documentation with 198 comprehensive docs including all tags, filters, and objects.

A specialized Model Context Protocol (MCP) server that provides instant access to complete Shopify Liquid documentation for AI assistants like Claude, Cursor, and other MCP-compatible tools.

🎯 Why This MCP Server?

vs. Official Shopify MCP

While Shopify provides an official MCP server that covers all Shopify APIs, this server is specifically optimized for Liquid template development:

Feature	Official Shopify MCP	This (Liquid MCP)
Focus	All Shopify APIs (Admin, Storefront, Functions, etc.)	Liquid templating only
Storage	Remote (queries shopify.dev)	Local (no network needed)
Speed	Network-dependent	Instant (<1ms)
Offline	❌ Requires internet	✅ Fully offline
Customization	Fixed documentation	Add your own docs
Coverage	General API docs	198 Liquid-specific docs
Runtime	Node.js	Python

Use Cases

Use Official Shopify MCP for:

• Admin API/GraphQL development
• App development with Shopify APIs
• Functions and POS extensions
• Real-time schema validation

Use This Liquid MCP for:

• Theme development with Liquid
• Liquid template debugging
• Offline development
• Faster Liquid reference lookups
• Project-specific Liquid snippets

Use Both! They complement each other perfectly - official MCP for APIs, this for Liquid.

✨ Features

• 🚀 Lightning Fast - Local SQLite FTS5 search (<1ms response time)
• 📚 Complete Coverage - 30 tags, 101 filters, 67 objects (198 total docs)
• 🔌 Offline First - No network requests, works anywhere
• 🐳 Docker Ready - One command deployment
• 🎨 IDE Integration - Works with VS Code, Cursor, Claude Desktop, Zed
• 🔧 Customizable - Add your own project-specific Liquid docs
• 📖 Rich Documentation - Full syntax, parameters, examples for everything
• 🔍 Smart Search - Full-text search with snippet highlighting

📦 Installation

Option 1: Using pip (Recommended)

pip install git+https://github.com/florinel-chis/shopify-liquid-mcp.git

Option 2: Using Docker

# Pull the image
docker pull florinel-chis/shopify-liquid-mcp:latest

# Or build locally
docker build -t shopify-liquid-mcp .
docker run -it shopify-liquid-mcp

Option 3: Using docker-compose

docker-compose up -d

Option 4: From Source

git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp
pip install -e .

🎮 Usage

With VS Code

Using Docker

Create or edit .vscode/settings.json:

{
  "mcp.servers": {
    "shopify-liquid": {
      "type": "docker",
      "image": "shopify-liquid-mcp:latest",
      "transport": "stdio"
    }
  }
}

Using Local Installation

Create .mcp.json in your project root:

{
  "mcpServers": {
    "shopify-liquid": {
      "type": "stdio",
      "command": "shopify-liquid-mcp"
    }
  }
}

Or add to VS Code settings:

{
  "mcp.servers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp",
      "args": [],
      "transport": "stdio"
    }
  }
}

With Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Using Docker

{
  "mcpServers": {
    "shopify-liquid": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

With Cursor

Add to Cursor's MCP configuration (Settings > Features > MCP Servers):

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "shopify-liquid": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
    }
  }
}

With Zed Editor

Create .zed/settings.json:

{
  "context_servers": {
    "shopify-liquid": {
      "command": "shopify-liquid-mcp"
    }
  }
}

With Continue.dev

Edit ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "shopify-liquid",
      "command": "shopify-liquid-mcp"
    }
  ]
}

🛠️ Available Tools

Once configured, your AI assistant has access to 7 specialized tools:

1. search_liquid_docs(queries: List[str])

Full-text search across all Shopify Liquid documentation.

Example:

AI: I'll search for "for loop" in the documentation...

2. get_liquid_tag(tag_name: str)

Get complete documentation for a specific tag.

Example:

AI: Let me get the documentation for the 'for' tag...

3. get_liquid_filter(filter_name: str)

Get complete documentation for a specific filter.

Example:

AI: I'll look up the 'upcase' filter documentation...

4. get_liquid_object(object_name: str)

Get complete documentation for a specific object.

Example:

AI: Let me check the 'product' object properties...

5. list_liquid_tags()

List all 30 available tags organized by category.

6. list_liquid_filters()

List all 101 available filters organized by category.

7. list_liquid_objects()

List all 67 available objects organized by category.

💬 Example Queries

Try asking your AI assistant:

Getting Documentation:

• "Show me documentation for the for loop tag"
• "How does the money filter work in Liquid?"
• "What properties are available on the product object?"

Searching:

• "Search for documentation about cart functionality"
• "Find all filters related to dates"
• "What objects can I use for collections?"

Listing:

• "List all Shopify Liquid tags"
• "Show me all available string filters"
• "What iteration tags are available?"

Building:

• "Help me display products in a grid"
• "How do I format dates in Liquid?"
• "Show me how to work with the cart"

📊 Documentation Coverage

Complete Reference

• 30 Liquid Tags

  • Control flow: if, unless, case, else
  • Iteration: for, break, continue, cycle, tablerow, paginate
  • Variables: assign, capture, increment, decrement, echo
  • Theme: layout, section, sections, render, include, content_for
  • HTML/Assets: form, style, stylesheet, javascript
  • Syntax: comment, raw, liquid, doc

• 101 Liquid Filters

  • String (24): upcase, downcase, capitalize, append, prepend, etc.
  • Array (13): join, sort, reverse, map, where, size, etc.
  • Math (11): plus, minus, times, divided_by, modulo, etc.
  • Money (4): money, money_with_currency, etc.
  • Image (5): image_url, image_tag, etc.
  • Color (9): color_darken, color_lighten, etc.
  • And more...

• 67 Liquid Objects

  • Store: shop, settings, theme, brand
  • Products: product, variant, collection, collections
  • Cart: cart, line_item, checkout
  • Customer: customer, address, company
  • Content: page, blog, article, comment
  • Media: image, video, media, model
  • And more...

🐳 Docker Usage

Quick Start

# Build the image
docker build -t shopify-liquid-mcp .

# Run the server
docker run -it --rm shopify-liquid-mcp

# Run with persistent data
docker run -it --rm -v mcp-data:/data shopify-liquid-mcp

Using docker-compose

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Shell access
docker-compose exec shopify-liquid-mcp bash

Custom Documentation

Add your project-specific Liquid docs:

# Create custom docs directory
mkdir custom-docs

# Add your .md files
cp my-snippets.md custom-docs/

# Mount in docker-compose.yml
volumes:
  - ./custom-docs:/docs/custom:ro

🔧 Development

Running Tests

# Run all tests
pytest

# Run specific test
pytest tests/test_ingest.py

# Run with coverage
pytest --cov=shopify_liquid_mcp

Manual Testing

# Test the server
python test_server.py

# Test indexing
python -m shopify_liquid_mcp.ingest

# Check database
sqlite3 ~/.mcp/shopify-liquid-docs/database.db "SELECT COUNT(*) FROM liquid_docs;"

Reindexing Documentation

# Force reindex
python -m shopify_liquid_mcp.ingest --force

# Custom database location
SHOPIFY_LIQUID_DB_PATH=/custom/path/db.sqlite python -m shopify_liquid_mcp.ingest

📖 Documentation

• Installation Guide
• VS Code Setup
• Docker Guide
• Contributing
• Examples
• API Reference

🤝 Contributing

Contributions welcome! Please read our Contributing Guide.

Quick Start

# Fork and clone
git clone https://github.com/florinel-chis/shopify-liquid-mcp.git
cd shopify-liquid-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install for development
pip install -e ".[dev]"

# Run tests
pytest

# Make changes and submit PR

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

• Inspired by Gemini API Docs MCP
• Built with FastMCP
• Documentation from Shopify Liquid API
• MCP Protocol by Anthropic

🔗 Related Projects

• Official Shopify Dev MCP - For Shopify API development
• FastMCP - MCP server framework
• Model Context Protocol - MCP specification

📞 Support

• 🐛 Issues
• 💬 Discussions
• 📧 Email

⭐ Star History

---

Made with ❤️ for the Shopify theme development community