JUHE API Marketplace
ashwin2912 avatar
MCP Server

Saleor MCP Server

A Model Context Protocol server that enables AI assistants to interact with Saleor e-commerce data including products, orders, customers, and more.

2
GitHub Stars
8/18/2025
Last Updated
MCP Server Configuration
1{
2 "name": "saleor",
3 "command": "poetry",
4 "args": [
5 "run",
6 "bm-mcp"
7 ],
8 "cwd": "/full/path/to/saleor-mcp-server",
9 "env": {
10 "SALEOR_API_URL": "http://localhost: 8000/graphql/",
11 "SALEOR_EMAIL": "your-email@example.com",
12 "SALEOR_PASSWORD": "your-password"
13 }
14}
JSON14 lines

README Documentation

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

Required Services

  1. 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:

⚡ 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

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

Quick Install

Quick Actions

Key Features

Model Context Protocol
Secure Communication
Real-time Updates
Open Source