README.md•11.2 kB
# Shopify Liquid MCP Server
> 🚀 **Fast, local, offline-first MCP server** for Shopify Liquid documentation with **198 comprehensive docs** including all tags, filters, and objects.
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://hub.docker.com/)
[](https://modelcontextprotocol.io/)
A specialized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](https://shopify.dev/docs/apps/build/devmcp) 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)
```bash
pip install git+https://github.com/florinel-chis/shopify-liquid-mcp.git
```
### Option 2: Using Docker
```bash
# 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
```bash
docker-compose up -d
```
### Option 4: From Source
```bash
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`:
```json
{
"mcp.servers": {
"shopify-liquid": {
"type": "docker",
"image": "shopify-liquid-mcp:latest",
"transport": "stdio"
}
}
}
```
#### Using Local Installation
Create `.mcp.json` in your project root:
```json
{
"mcpServers": {
"shopify-liquid": {
"type": "stdio",
"command": "shopify-liquid-mcp"
}
}
}
```
Or add to VS Code settings:
```json
{
"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
```json
{
"mcpServers": {
"shopify-liquid": {
"type": "stdio",
"command": "docker",
"args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
}
}
}
```
#### Using Local Installation
```json
{
"mcpServers": {
"shopify-liquid": {
"command": "shopify-liquid-mcp"
}
}
}
```
### With Cursor
Add to Cursor's MCP configuration (Settings > Features > MCP Servers):
```json
{
"mcpServers": {
"shopify-liquid": {
"command": "shopify-liquid-mcp"
}
}
}
```
Or with Docker:
```json
{
"mcpServers": {
"shopify-liquid": {
"command": "docker",
"args": ["run", "-i", "--rm", "shopify-liquid-mcp:latest"]
}
}
}
```
### With Zed Editor
Create `.zed/settings.json`:
```json
{
"context_servers": {
"shopify-liquid": {
"command": "shopify-liquid-mcp"
}
}
}
```
### With Continue.dev
Edit `~/.continue/config.json`:
```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
```bash
# 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
```bash
# 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:
```bash
# 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
```bash
# Run all tests
pytest
# Run specific test
pytest tests/test_ingest.py
# Run with coverage
pytest --cov=shopify_liquid_mcp
```
### Manual Testing
```bash
# 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
```bash
# 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](./docs/INSTALLATION.md)
- [VS Code Setup](./docs/VSCODE.md)
- [Docker Guide](./docs/DOCKER.md)
- [Contributing](./CONTRIBUTING.md)
- [Examples](./EXAMPLES.md)
- [API Reference](./docs/API.md)
## 🤝 Contributing
Contributions welcome! Please read our [Contributing Guide](./CONTRIBUTING.md).
### Quick Start
```bash
# 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](./LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by [Gemini API Docs MCP](https://github.com/philschmid/gemini-api-docs-mcp)
- Built with [FastMCP](https://github.com/jlowin/fastmcp)
- Documentation from [Shopify Liquid API](https://shopify.dev/docs/api/liquid)
- MCP Protocol by [Anthropic](https://www.anthropic.com/)
## 🔗 Related Projects
- [Official Shopify Dev MCP](https://shopify.dev/docs/apps/build/devmcp) - For Shopify API development
- [FastMCP](https://github.com/jlowin/fastmcp) - MCP server framework
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification
## 📞 Support
- 🐛 [Issues](https://github.com/florinel-chis/shopify-liquid-mcp/issues)
- 💬 [Discussions](https://github.com/florinel-chis/shopify-liquid-mcp/discussions)
- 📧 [Email](mailto:your.email@example.com)
## ⭐ Star History
[](https://star-history.com/#florinel-chis/shopify-liquid-mcp&Date)
---
**Made with ❤️ for the Shopify theme development community**