shopify-liquid-mcp by florinel-chis - MCP Server

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

🤝 Contributing

Contributions welcome! Please read our .

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

florinel-chis/shopify-liquid-mcp

Shopify Liquid MCP Server

🎯 Why This MCP Server?

vs. Official Shopify MCP

Use Cases

✨ Features

📦 Installation

Option 1: Using pip (Recommended)

Option 2: Using Docker

Option 3: Using docker-compose

Option 4: From Source

🎮 Usage

With VS Code

Using Docker

Using Local Installation

With Claude Desktop

Using Docker

Using Local Installation

With Cursor

With Zed Editor

With Continue.dev

🛠️ Available Tools

1. search_liquid_docs(queries: List[str])

2. get_liquid_tag(tag_name: str)

3. get_liquid_filter(filter_name: str)

4. get_liquid_object(object_name: str)

5. list_liquid_tags()

6. list_liquid_filters()

7. list_liquid_objects()

💬 Example Queries

📊 Documentation Coverage

Complete Reference

🐳 Docker Usage

Quick Start

Using docker-compose

Custom Documentation

🔧 Development

Running Tests

Manual Testing

Reindexing Documentation

📖 Documentation

🤝 Contributing

Quick Start

📜 License

🙏 Acknowledgments

🔗 Related Projects

📞 Support

⭐ Star History

1. `search_liquid_docs(queries: List[str])`

2. `get_liquid_tag(tag_name: str)`

3. `get_liquid_filter(filter_name: str)`

4. `get_liquid_object(object_name: str)`

5. `list_liquid_tags()`

6. `list_liquid_filters()`

7. `list_liquid_objects()`