Plytix MCP Server
Supplyline/plytix-mcp
MCP stateless para integração com Plytix PIM e automação de dados de produtos
Ver no GitHubServidor MCP stateless que conecta Claude e outros assistentes de IA diretamente à API Plytix PIM. Oferece 51 ferramentas para leitura e escrita de dados de produtos, ativos, categorias e relacionamentos, ideal para automação de e-commerce sem necessidade de persistência local.
Instalação
npx convez-ai Supplyline/plytix-mcp1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automação de gestão de catálogo de produtos em tempo real
- Assistentes de IA para busca e lookup inteligente de informações de produtos
- Integrações de e-commerce com atualização de metadados e atributos
- Deployment remoto em Cloudflare Workers para acesso mobile/web
Veredito

MCP server robusto e bem documentado para integração PIM, com suporte a deployment remoto e autenticação automática. Excelente para equipes de e-commerce que precisam de acesso programático ao Plytix sem overhead de persistência.
README
A tradução para o português deste README ainda está na fila.
Plytix MCP Server
A lightweight, stateless Model Context Protocol (MCP) server that provides AI assistants with live access to Plytix PIM (Product Information Management) data. This server enables AI tools like Claude Desktop, Claude mobile app, and other MCP clients to search, look up, and retrieve product information directly from the Plytix API.
Note: This is a stateless, live API tool for read and write operations. For sync, caching, or ETL workflows, pair it with a separate persistence layer of your choosing.
Features
- 51 MCP tools via stdio and 46 via the remote worker
- Smart product lookup with automatic identifier detection (SKU, MPN, GTIN, label)
- Family & inheritance tracking with overwritten_attributes support
- Schema discovery for attributes and search filters
- Automatic authentication with token refresh
- Rate limit handling with exponential backoff
- Zero persistence — stateless, no database required
- Remote server support — Deploy to Cloudflare Workers for mobile/web access
Installation
Prerequisites
- Node.js 18+ (Node 20+ recommended)
- Plytix PIM account with API access
Setup
- Clone and install:
git clone https://github.com/Supplyline/plytix-mcp.git
cd plytix-mcp
npm install
- Configure credentials:
cp .env.example .env
# Edit .env with your Plytix API credentials
- Build the project:
npm run build
Usage
With Claude Desktop
Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"plytix": {
"command": "node",
"args": ["/path/to/plytix-mcp/dist/index.js"],
"env": {
"PLYTIX_API_KEY": "your_api_key_here",
"PLYTIX_API_PASSWORD": "your_api_password_here"
}
}
}
}
Standalone
npm start # Production mode
npm run dev # Development with hot reload
Remote Server (Cloudflare Workers)
Deploy as a remote MCP server for access from Claude mobile app, web clients, or shared team access.
Quick Deploy
# Install dependencies (includes wrangler)
npm install
# Login to Cloudflare
wrangler login
# Deploy to Cloudflare Workers
npm run deploy
Using the Remote Server
Once deployed, connect from any MCP client using the deployed URL and your Plytix credentials:
# With Claude Desktop (using mcp-remote)
npx mcp-remote https://plytix-mcp.your-subdomain.workers.dev/mcp \
--header "X-Plytix-API-Key: YOUR_API_KEY" \
--header "X-Plytix-API-Password: YOUR_API_PASSWORD"
The remote worker exposes 46 tools. It intentionally omits local-only utilities and filesystem tools: identifier_detect, identifier_normalize, match_score, products_batch_update_manifest, and products_batch_export_to_file.
Local Development
npm run dev:worker # Start local worker at localhost:8787
npm run test:worker # Test the worker endpoints
For detailed setup instructions, see docs/remote-setup.md.
Available Tools
Product Tools
| Tool | Description |
|---|---|
products_lookup | Smart lookup by any identifier (auto-detects ID, SKU, MPN, GTIN, label) |
products_get | Get single product by ID with full details and overwritten_attributes |
products_get_full | Get one product with related family, variants, categories, and assets |
products_search | Advanced search with filters, pagination, and sorting |
products_find | Simple multi-criteria search (SKU, MPN, MNO, GTIN, label, fuzzy) |
products_batch_export | Capped inline product snapshot by search, SKU, or product ID |
products_batch_export_to_file | Stdio-only JSONL/NDJSON product export under PLYTIX_MCP_EXPORT_DIR |
products_create | Create a new product |
products_update | Partial update to product fields/attributes |
products_batch_update | Apply a small guarded product-update batch |
products_batch_update_manifest | Stdio-only guarded product updates from a local JSON manifest |
products_assign_family | Assign or unassign a product family |
products_set_attribute | Atomic set of one attribute value |
products_clear_attribute | Atomic clear of one attribute value |
Family Tools
| Tool | Description |
|---|---|
families_list | List or search product families |
families_get | Get single family with linked attributes |
families_create | Create a new product family |
families_link_attribute | Link one or more attributes to a family |
families_unlink_attribute | Unlink one or more attributes from a family |
families_list_attributes | List attributes directly linked to a family |
families_list_all_attributes | List direct and inherited family attributes |
Attribute & Filter Tools
| Tool | Description |
|---|---|
attributes_list | List all attributes (system + custom) with types and options |
attributes_get | Get full metadata for one attribute label |
attributes_get_options | Get allowed values for a selectable attribute |
attributes_filters | Deprecated alias for product filter discovery |
products_filters | Get product search filter metadata |
assets_filters | Get asset search filter metadata |
relationships_filters | Get relationship search filter metadata |
Asset Tools
| Tool | Description |
|---|---|
assets_get | Get one asset by ID |
assets_search | Search account assets |
assets_update | Update asset metadata (filename, categories) |
assets_list | List assets (images, videos, documents) linked to a product |
assets_link | Link an asset to a product |
assets_unlink | Unlink an asset from a product |
Category Tools
| Tool | Description |
|---|---|
categories_search | Search existing categories |
categories_list | List categories associated with a product |
categories_link | Link a category to a product |
categories_unlink | Unlink a category from a product |
Variant Tools
| Tool | Description |
|---|---|
variants_create | Create a variant under a parent product |
variants_link | Link an existing product as a variant |
variants_unlink | Unlink a variant from its parent without deleting it |
variants_list | List variants for a product |
variants_resync | Reset variant attributes to inherit parent values |
Relationship Tools
| Tool | Description |
|---|---|
relationships_get | Get a relationship definition by ID |
relationships_search | Search relationship definitions |
relationships_link_product | Link one related product row in a relationship |
relationships_unlink_product | Unlink one related product row in a relationship |
relationships_set_quantity | Update quantity for one related product row |
Identifier Utilities (Stdio Only)
| Tool | Description |
|---|---|
identifier_detect | Detect identifier type from raw value |
identifier_normalize | Normalize identifier for matching |
match_score | Score identifier-product match confidence |
The remote worker exposes every tool above except the three identifier utilities in the final section and the two stdio-only filesystem tools: products_batch_update_manifest and products_batch_export_to_file.
Smart Lookup System
The products_lookup tool automatically detects identifier types and uses staged search strategies:
Detection priority:
- MongoDB ObjectId (24-char hex) →
id(confidence: 1.0) - GTIN (8/12/13/14 digits) →
gtin(confidence: 0.95) - Contains spaces →
label(confidence: 0.9) - Dashed alphanumeric →
mpn(confidence: 0.8) - Alphanumeric with separators →
sku(confidence: 0.7)
Search strategies (in order):
- Direct ID lookup (if detected as ID)
- Exact field matches (SKU, GTIN, MPN, MNO)
- Text search across multiple fields
- Broad LIKE search (last resort)
Example:
Input: "LMI-PD-123"
→ Detected as: sku (confidence: 0.7)
→ Tries: sku_eq, mpn fields, text_search, broad_like
→ Returns: best match with confidence score
Inheritance Tracking
Products return an overwritten_attributes array listing which attributes are explicitly set (not inherited from family). Use this with:
product_family_id— The family this product belongs tofamilies_get— Retrieve family-level default values- Compare to determine inherited vs overwritten values
Configuration
Environment Variables
| Variable | Required | Default | Description |
|---|---|---|---|
PLYTIX_API_KEY | ✅ | — | Your Plytix API key |
PLYTIX_API_PASSWORD | ✅ | — | Your Plytix API password |
PLYTIX_API_BASE | ❌ | https://pim.plytix.com | Plytix API base URL |
PLYTIX_AUTH_URL | ❌ | https://auth.plytix.com/auth/api/get-token | Auth endpoint |
PLYTIX_MPN_LABELS | ❌ | ["attributes.mpn"] | JSON array of MPN attribute labels |
PLYTIX_MNO_LABELS | ❌ | ["attributes.model_no"] | JSON array of MNO attribute labels |
PLYTIX_MCP_EXPORT_DIR | ❌ | — | Required only for products_batch_export_to_file; limits file exports to this directory |
Development
Scripts
| Command | Description |
|---|---|
npm run dev | Development server with hot reload (stdio) |
npm run dev:worker | Development server for Cloudflare Workers |
npm run build | Build TypeScript to JavaScript |
npm run deploy | Deploy to Cloudflare Workers |
npm start | Start production server (stdio) |
npm test | Run unit tests (vitest) |
npm run test:watch | Run tests in watch mode |
npm run test:mcp | Test MCP protocol handshake |
npm run test:worker | Test worker endpoints |
npm run test:all | Build + unit + integration + MCP tests |
npm run typecheck | Type check without building |
Architecture
src/
index.ts # MCP server entry point (stdio transport)
worker.ts # Cloudflare Worker entry point (HTTP transport)
client.ts # Plytix API client with auth & rate limiting
worker-client.ts # Worker-compatible client (BYOK credentials)
worker-lookup.ts # Worker-compatible smart lookup
types.ts # TypeScript types
lookup/
identifier.ts # Identifier type detection
lookup.ts # Smart lookup with staged search
tools/
products.ts # Product tools (lookup, get, search, find, write ops)
families.ts # Family tools (list, get, create, attribute membership)
attributes.ts # Attribute metadata + filter discovery tools
product-attributes.ts # Atomic product attribute write tools
assets.ts # Asset get/search/update + product asset link tools
categories.ts # Category search + product category link tools
variants.ts # Variant lifecycle tools
relationships.ts # Relationship discovery + product relationship write tools
extensions/ # Optional deployment-specific customizations
wrangler.toml # Cloudflare Workers configuration
docs/
remote-setup.md # Remote server setup guide
Design Principles
This MCP server is intentionally stateless and lightweight:
- No database — All queries go directly to Plytix API
- No sync/caching layer — Fresh data on every request
- No background jobs — Request/response only
- Ephemeral in-memory cache — Brief (60s) request deduplication, cleared on restart
For ETL, sync, or persistent caching needs, pair this server with a separate persistence layer.
License
MIT License — see LICENSE file for details.
Support
- Issues: GitHub Issues
- Plytix API: Plytix Documentation
- MCP Protocol: Model Context Protocol