How do I use Tiendanube MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Tiendanube MCP Server list all products with stock lower than 10 units" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Tiendanube MCP Server - Docker Setup

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

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": "john@example.com"
        },
        "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

Never commit - Add to .gitignore
Use environment-specific tokens - Separate dev/prod credentials
Enable HTTPS - Use reverse proxy (nginx/traefik) for production
Rate limiting - Consider adding rate limits for production
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

📄 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

Tiendanube MCP Server - Docker Setup

🚀 Features

Resources

Transport Modes

📋 Prerequisites

🔧 Setup

1. Clone or Create Project Structure

2. Configure Environment Variables

3. Build and Run

🌐 Accessing the Server

SSE Transport (Default)

Streamable HTTP Transport

🔍 Health Check

📊 API Endpoints

Products

Orders

Customers

Categories

Coupons

Store

🎯 Usage Examples

Connect from Python Client

Connect from cURL

Advanced Examples

🐳 Docker Commands

🔐 Security Notes

🔄 Updating

📝 Logging

🐛 Troubleshooting

Server won't start

Connection refused

Permission errors

🌟 Production Deployment

With Nginx Reverse Proxy

With Docker Swarm

Environment Variables for Production

📚 Resources

📄 License

🤝 Contributing

📧 Support

Resources

Latest Blog Posts

MCP directory API