nuvemshop

This MCP server provides a Tiendanube/Nuvemshop integration with multiple transport options (SSE, streamable HTTP, and STDIO) to enable real-time updates and RPC-style interactions with a Tiendanube store. It exposes endpoints to manage core resources such as Products, Orders, Customers, Categories, Coupons, and Store information, all through a unified JSON-RPC style interface. Clients can connect via SSE at /sse for event streaming, or use the /mcp endpoint when using the streamable HTTP transport. The API supports rich query capabilities (filters, pagination, and CRUD operations) and includes example payloads for common workflows like listing products, creating orders, and retrieving store details. The server is designed to work behind a reverse proxy for production and can be deployed via Docker Compose for local development.

To use the server, first start the container using the configured image. Set environment variables for your Tiendanube credentials (access token and store ID) and choose a transport by adjusting MCP_TRANSPORT in the environment (sse by default, or streamable-http for the HTTP RPC style). Then interact with the available methods by sending JSON-RPC payloads to the designated endpoints. For example, you can list products using the tools/call method with arguments specifying the list_products action and your desired filters, or create an order by providing the products, customer details, and payment status.

Prerequisites:

• Docker and Docker Compose installed on your machine
• Tiendanube API credentials: Access Token and Store ID

1. Prepare project structure

• Clone or create a project directory:

mkdir tiendanube-mcp
cd tiendanube-mcp

2. Create required files (as listed in the README)

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

3. Configure environment variables Create a .env file with your credentials and server settings, for example:

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

4. Build and run (Docker Compose)

• Build the Docker image:

docker-compose build

• Start the server in detached mode:

docker-compose up -d

• View logs as needed:

docker-compose logs -f

• Stop the server:

docker-compose down

5. Access and test

• SSE endpoint: http://localhost:8080/sse
• If you switch to streamable-http transport, update MCP_TRANSPORT to streamable-http and use http endpoint: http://localhost:8080/mcp

Optional: for production deployment, ensure you configure a reverse proxy (Nginx/Traefik) and set appropriate TLS/SSL settings in your environment.

Tips and common issues:

• Never commit the .env file to version control. Add it to your .gitignore and manage credentials securely.
• If the server won’t start, inspect docker-compose logs for the tiendanube-mcp service, and validate that MCP_PORT is not in use by another process.
• When using production-like traffic, consider enabling HTTPS behind a reverse proxy and applying rate limiting.
• For SSE, ensure proxy buffers are disabled and timeouts are configured to support long-lived connections.
• If you need to switch transports, remember to adjust MCP_TRANSPORT and the corresponding endpoint URLs in your clients.
• Keep your Tiendanube API credentials scoped to the appropriate store and environment (dev vs prod).