README.md•7.88 kB
# Saleor MCP Server
A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for Saleor. This server enables an MCP client to interact with Saleor e-commerce data including products, orders, customers, and more.
[](https://modelcontextprotocol.io)
[](https://python.org)
[](https://python-poetry.org)
## 🚀 Features
-**Product Management**: Query and browse Saleor products with rich formatting
## 📋 Prerequisites
### Required Software
1. **Python 3.10 or higher**
```bash
python --version # Should be 3.10+
```
2. **Poetry** (recommended) or pip
```bash
# Install Poetry
curl -sSL https://install.python-poetry.org | python3 -
# Or via pip
pip install poetry
```
3. **Claude Desktop**
- Download from [claude.ai/desktop](https://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](https://docs.saleor.io/docs/3.x/developer)**
**Quick Start with Docker:**
```bash
# 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](https://docs.saleor.io/docs/3.x/developer/installation/docker-compose)
- 🐍 [Local Python Setup](https://docs.saleor.io/docs/3.x/developer/installation)
- ☁️ [Saleor Cloud](https://cloud.saleor.io/)
## ⚡ Quick Start
### 1. Clone and Install
```bash
# 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
```bash
# Copy environment template
cp .env.example .env
# Edit configuration
nano .env # or your preferred editor
```
**Required Configuration (.env):**
```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
```bash
# 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
```bash
# 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)**
```json
{
"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**
```json
{
"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
```bash
# 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
```bash
# 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
```bash
# 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**
```bash
# Verify Saleor is running
curl http://localhost:8000/graphql/
# Test credentials
poetry run python scripts/test-connection.py
```
**Import Errors**
```bash
# Reinstall dependencies
poetry install --sync
# Check Python version
python --version # Should be 3.10+
```
**Claude Desktop Issues**
```bash
# 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
```bash
# 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](https://docs.saleor.io/)
- [MCP Documentation](https://modelcontextprotocol.io/docs)
- [Report Issues](https://github.com/yourusername/saleor-mcp-server/issues)
- [Discussions](https://github.com/yourusername/saleor-mcp-server/discussions)
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [Anthropic](https://www.anthropic.com/) for the Model Context Protocol
- [Saleor](https://saleor.io/) 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
---