Saleor MCP Server

A Model Context Protocol (MCP) server for Saleor. This server enables an MCP client to interact with Saleor e-commerce data including products, orders, customers, and more.

🚀 Features

-Product Management: Query and browse Saleor products with rich formatting

📋 Prerequisites

Required Software

1. Python 3.10 or higher

   python --version  # Should be 3.10+
   

2. Poetry (recommended) or pip

   # Install Poetry
   curl -sSL https://install.python-poetry.org | python3 -
   
   # Or via pip
   pip install poetry
   

3. Claude Desktop

   • Download from claude.ai/desktop

Required Services

4. Running Saleor Instance
   • Local development server

🏪 Setting Up Saleor

You need a running Saleor instance to connect to. Choose one of these options:

Option 1: Local Development (Recommended for Testing)

Follow the official Saleor documentation to set up a local instance:

📚 Saleor Developer Documentation

Quick Start with Docker:

# Clone Saleor
git clone https://github.com/saleor/saleor-platform.git
cd saleor-platform

# Start with Docker Compose
docker-compose up -d

# Access at http://localhost:8000/graphql/

Detailed Setup Guides:

• 🐳 Docker Setup
• 🐍 Local Python Setup
• ☁️ Saleor Cloud

⚡ Quick Start

1. Clone and Install

# Clone the repository
git clone https://github.com/yourusername/saleor-mcp-server.git
cd saleor-mcp-server

# Install dependencies
poetry install

# Or with pip
pip install -r requirements.txt
pip install -e .

2. Configure Environment

# Copy environment template
cp .env.example .env

# Edit configuration
nano .env  # or your preferred editor

Required Configuration (.env):

# Saleor API Configuration
SALEOR_API_URL=http://localhost:8000/graphql/
SALEOR_EMAIL=your-email@example.com
SALEOR_PASSWORD=your-password

# Optional: Advanced Settings
LOG_LEVEL=INFO
TOKEN_REFRESH_THRESHOLD=300
SERVER_NAME=saleor
DEFAULT_PRODUCT_LIMIT=20
MAX_PRODUCT_LIMIT=100

3. Test the Connection

# Test your configuration
poetry run python scripts/test-tools.py

# Or test the server directly
TEST_MODE=true poetry run bm-mcp

Expected output:

🧪 Testing Saleor connection...
✅ Connection successful!
📦 Testing product query...
✅ Found 3 products
   • Product Name (ID: ...)
🎉 All tests passed!

4. Test with MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector poetry run bm-mcp

This opens a web interface at http://localhost:5173 where you can:

• Test the connection
• Call the get_products tool
• See formatted responses

🖥️ Claude Desktop Setup

1. Find your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude.desktopconfig
• Windows: %APPDATA%\Claude\claude.desktopconfig
• Linux: ~/.config/Claude/claude.desktopconfig

2. Add the server configuration:

Option A: Using Poetry (Recommended)

{
  "mcpServers": {
    "saleor": {
      "command": "poetry",
      "args": ["run", "bm-mcp"],
      "cwd": "/full/path/to/saleor-mcp-server",
      "env": {
        "SALEOR_API_URL": "http://localhost:8000/graphql/",
        "SALEOR_EMAIL": "your-email@example.com",
        "SALEOR_PASSWORD": "your-password"
      }
    }
  }
}

Option B: Direct Script

{
  "mcpServers": {
    "saleor": {
      "command": "/full/path/to/saleor-mcp-server/.venv/bin/bm-mcp",
      "args": []
    }
  }
}

3. Restart Claude Desktop

After updating the configuration, restart Claude Desktop completely.

🧪 Testing

Command Line Testing

# Test imports and configuration
poetry run python -c "from bm_mcp.main import main; print('✅ Import successful')"

# Test with environment flag
TEST_MODE=true poetry run bm-mcp

# Test specific tools
poetry run python scripts/test-tools.py

Interactive Testing

# Start MCP Inspector
npx @modelcontextprotocol/inspector poetry run bm-mcp

# Test in Claude Desktop
# Ask: "Show me products from my store"
# Ask: "Get the latest products from my Saleor instance"

Usage Examples

Once configured, you can ask Claude questions like:

• "Show me the latest products in my store"
• "What products do I have available?"

Available Tools

• get_products: Retrieve products with optional filtering
  • Parameters: limit, channel, category_id
  • Returns: Formatted product list with names, prices, availability

🛠️ Development

Project Structure

saleor-mcp-server/
├── bm_mcp/
│   ├── client/         # Saleor API client
│   ├── config/         # Configuration management
│   ├── formatters/     # Data formatting
│   ├── tools/          # MCP tool implementations
│   ├── utils/          # Utilities and helpers
│   └── main.py         # Entry point
├── scripts/            # Testing and utility scripts
├── tests/              # Unit tests
├── .env.example        # Environment template
└── README.md

Adding New Tools

1. Create tool class in bm_mcp/tools/
2. Inherit from appropriate base class
3. Register in main.py
4. Add tests in tests/

Running Tests

# Run unit tests
poetry run pytest

# Run with coverage
poetry run pytest --cov=bm_mcp

# Test specific functionality
poetry run python scripts/test-tools.py

🔧 Troubleshooting

Common Issues

Connection Errors

# Verify Saleor is running
curl http://localhost:8000/graphql/

# Test credentials
poetry run python scripts/test-connection.py

Import Errors

# Reinstall dependencies
poetry install --sync

# Check Python version
python --version  # Should be 3.10+

Claude Desktop Issues

# Check logs
tail -f ~/Library/Logs/Claude/mcp-server-saleor.log

# Verify config syntax
cat ~/Library/Application\ Support/Claude/claude.desktopconfig | python -m json.tool

Debug Mode

# Enable debug logging
LOG_LEVEL=DEBUG poetry run bm-mcp

# Test mode with verbose output
TEST_MODE=true LOG_LEVEL=DEBUG poetry run bm-mcp

Getting Help

• Saleor Documentation
• MCP Documentation
• Report Issues
• Discussions

License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Anthropic for the Model Context Protocol
• Saleor for the excellent e-commerce platform
• The open-source community for inspiration and tools

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (poetry run pytest)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

---