Tiendanube Server

A complete Model Context Protocol (MCP) server for Tiendanube/Nuvemshop API with Docker support and SSE transport.

🚀 Features

Resources

• Products: Full CRUD with advanced filtering (stock, price, categories, SKU)
• Orders: Complete order management with history tracking
• Customers: Customer management with addresses and billing
• Categories: Category hierarchy management
• Coupons: Discount coupon management
• Store: Store information and settings

Transport Modes

• ✅ SSE (Server-Sent Events) - For web-based clients
• ✅ Streamable HTTP - Modern HTTP transport
• ✅ STDIO - For CLI/terminal usage

📋 Prerequisites

• Docker and Docker Compose
• Tiendanube API credentials:
  • Access Token
  • Store ID

🔧 Setup

1. Clone or Create Project Structure

mkdir tiendanube-mcp
cd tiendanube-mcp

Create the following files:

• tiendanube_server.py (main server code)
• Dockerfile
• docker-compose.yml
• requirements.txt
• .env (from .env.example)

2. Configure Environment Variables

Create .env file:

TIENDANUBE_ACCESS_TOKEN=your_access_token_here
TIENDANUBE_STORE_ID=your_store_id_here
TIENDANUBE_BASE_URL=https://api.tiendanube.com/v1

# Server Configuration
MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=INFO

3. Build and Run

# Build the Docker image
docker-compose build

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

🌐 Accessing the Server

SSE Transport (Default)

URL: http://localhost:8080/sse

Streamable HTTP Transport

Change .env:

MCP_TRANSPORT=streamable-http

URL: http://localhost:8080/mcp

🔍 Health Check

curl http://localhost:8080/health

📊 API Endpoints

Products

• list_products - List/search products with filters
• get_product - Get product by ID
• get_product_by_sku - Get product by SKU
• create_product - Create new product with variants
• update_product - Update product information
• delete_product - Delete product
• update_product_stock_price - Bulk update stock/prices

Orders

• list_orders - List orders with filters
• get_order - Get order details
• get_order_history_values - Get value change history
• get_order_history_editions - Get edition changelog
• create_order - Create new order
• update_order - Update order
• close_order - Close order
• open_order - Reopen order
• cancel_order - Cancel order

Customers

• list_customers - List/search customers
• get_customer - Get customer details
• create_customer - Create new customer
• update_customer - Update customer
• delete_customer - Delete customer

Categories

• list_categories - List all categories
• get_category - Get category details
• create_category - Create category
• update_category - Update category
• delete_category - Delete category

Coupons

• list_coupons - List all coupons
• get_coupon - Get coupon details
• create_coupon - Create discount coupon

Store

• get_store - Get store information

🎯 Usage Examples

Connect from Python Client

import requests
import json

# SSE endpoint
url = "http://localhost:8080/sse"

# List products
payload = {
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
        "name": "list_products",
        "arguments": {
            "query": "shirt",
            "per_page": 10
        }
    },
    "id": 1
}

response = requests.post(url, json=payload)
print(response.json())

Connect from cURL

# List products
curl -X POST http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": {
        "published": true,
        "per_page": 20
      }
    },
    "id": 1
  }'

Advanced Examples

# Get low stock products
curl -X POST http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "list_products",
      "arguments": {
        "max_stock": 10,
        "published": true
      }
    },
    "id": 1
  }'

# Create order
curl -X POST http://localhost:8080/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "create_order",
      "arguments": {
        "products": [{"variant_id": 123456, "quantity": 2}],
        "customer": {
          "name": "John Doe",
          "email": "[email protected]"
        },
        "payment_status": "paid"
      }
    },
    "id": 1
  }'

🐳 Docker Commands

# Build
docker-compose build

# Start
docker-compose up -d

# Logs
docker-compose logs -f tiendanube-mcp

# Restart
docker-compose restart

# Stop
docker-compose down

# Remove everything
docker-compose down -v --rmi all

# Shell access
docker exec -it tiendanube-mcp-server bash

🔐 Security Notes

1. Never commit .env file - Add to .gitignore
2. Use environment-specific tokens - Separate dev/prod credentials
3. Enable HTTPS - Use reverse proxy (nginx/traefik) for production
4. Rate limiting - Consider adding rate limits for production
5. CORS configuration - Configure allowed origins if exposing publicly

🔄 Updating

# Pull latest changes
git pull

# Rebuild
docker-compose down
docker-compose build --no-cache
docker-compose up -d

📝 Logging

Logs are configured with rotation:

• Max size: 10MB per file
• Max files: 3
• Location: Docker logs (use docker-compose logs)

View logs:

# All logs
docker-compose logs -f

# Last 100 lines
docker-compose logs --tail=100

# Specific service
docker-compose logs -f tiendanube-mcp

🐛 Troubleshooting

Server won't start

# Check logs
docker-compose logs tiendanube-mcp

# Verify environment variables
docker-compose config

# Test API credentials
curl -H "Authentication: bearer YOUR_TOKEN" \
  https://api.tiendanube.com/v1/YOUR_STORE_ID/store

Connection refused

• Verify port 8080 is not in use: netstat -tuln | grep 8080
• Check firewall settings
• Ensure container is running: docker ps

Permission errors

# Fix permissions
chmod +x start.sh

🌟 Production Deployment

With Nginx Reverse Proxy

server {
    listen 443 ssl http2;
    server_name mcp.yourdomain.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location /sse {
        proxy_pass http://localhost:8080/sse;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
        
        # SSE specific
        proxy_buffering off;
        proxy_read_timeout 86400;
    }
}

With Docker Swarm

docker stack deploy -c docker-compose.yml tiendanube

Environment Variables for Production

TIENDANUBE_ACCESS_TOKEN=prod_token
TIENDANUBE_STORE_ID=prod_store_id
MCP_TRANSPORT=sse
MCP_HOST=0.0.0.0
MCP_PORT=8080
LOG_LEVEL=WARNING

📚 Resources

• Tiendanube API Documentation
• MCP Protocol Specification
• Docker Documentation

📄 License

MIT License - See LICENSE file for details

🤝 Contributing

Contributions are welcome! Please open an issue or submit a pull request.

📧 Support

For issues related to:

• This MCP Server: Open a GitHub issue
• Tiendanube API: Contact Tiendanube support
• MCP Protocol: Check MCP documentation