Tiendanube MCP Server

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

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": "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