WooCommerce MCP open source: acesso só de leitura à loja para agentes de IA

#WooCommerce MCP open source: acesso só de leitura à loja para agentes de IA

Em projetos WooCommerce-para-ERP, a mesma pergunta aparece nas calls de kickoff: o AI consegue só consultar a loja? A resposta honesta é sim - se não puder estragar nada. Essa restrição é a razão pela qual lançámos o woocommerce-mcp como open source: um servidor Model Context Protocol (MCP) pequeno que responde a perguntas em tempo real sobre produtos, stock, encomendas, vendas e artigos através das APIs REST oficiais, com zero escritas e sem plugin instalado na loja.

Este artigo é o guia de lançamento e operação do pacote publicado. Se precisar de desenhar um servidor à medida (incluindo ferramentas que mutam estado ou deploy em Workers), use o programa comercial de desenvolvimento de servidores MCP e o pilar de integração MCP e IA. Para o lado comércio, veja integração WooCommerce ERP e o trabalho de programador de WooCommerce.

#TL;DR

• Pacote: @wppoland/woocommerce-mcp no npm (o binário CLI continua a chamar-se woocommerce-mcp).
• Registry: io.github.wppoland/woocommerce-mcp no MCP Registry oficial.
• Cinco ferramentas só de leitura sobre REST WooCommerce / WordPress - apenas chaves Read.
• Sem plugin no lado da loja. MIT, TypeScript, Node 18+.
• Use isto quando os agentes precisam de factos do catálogo e das encomendas; construa MCP à medida quando precisar de escritas ou ferramentas específicas de ERP.

#Porque lançámos um servidor MCP só de leitura

O MCP dá a um anfitrião LLM (Claude Desktop, Cursor, um agente próprio) uma superfície tipada tools/list em vez de forçar o modelo a inventar caminhos /wp-json/wc/v3/. Isso é útil. Também é perigoso se todas as ferramentas puderem mutar inventário, reembolsos ou dados de clientes.

No trabalho de sync ERP vemos dois modos de falha com mais frequência do que falhas “inteligentes” de prompt:

1. Sobre-venda em campanhas de pico (Black Friday, campanhas da Worten/FNAC, ou o pico de natalícia nas lojas de moda em Lisboa e Porto) porque um caminho de escrita correu em corrida com o feed do armazém.
2. Alterações acidentais de estado quando um agente “prestativamente” marcou encomendas como concluídas enquanto depurava.

O MCP só de leitura não corrige um mau desenho de ERP. Remove uma classe de escritas acidentais do plano do agente. A loja continua a ser o sistema de registo através da REST do WooCommerce. O agente só pergunta.

Documentámos as decisões de protocolo no Tech Radar: Anthropic MCP e a superfície de autenticação no guia de integração MCP e IA. Este lançamento é o binário concreto que pode instalar hoje.

#O que foi publicado (julho 2026)

A versão 0.1.1 é o alvo de instalação. A 0.1.0 existiu brevemente como um stub falhado no registo - uma linha _auth legada em conflito no ~/.npmrc local partiu esse publish. Ignore a 0.1.0.

#Porque o nome no npm é @wppoland/woocommerce-mcp

O nome sem prefixo woocommerce-mcp está bloqueado no npm (E403) depois de outra parte o ter unpublished. Publicamos como @wppoland/woocommerce-mcp. Use esse nome em npm install / npx. O campo bin em package.json continua a expor o comando woocommerce-mcp, por isso as configs do Claude Desktop e do Cursor mantêm o mesmo nome de binário.

O mcpName em package.json é io.github.wppoland/woocommerce-mcp. Essa string tem de coincidir com o campo name do server.json do MCP Registry para a verificação de propriedade funcionar quando publica com o CLI oficial mcp-publisher.

#Superfície de ferramentas

Tudo valida na fronteira MCP e depois chama a REST. Não há caminho neste pacote que crie produtos, atualize stock, reembolse encomendas ou instale plugins.

#Perguntas que estas ferramentas respondem de verdade

• Quais SKUs estão a stock zero antes de uma campanha?
• O que vendemos no mês passado em termos líquidos que a loja já reporta?
• Quais foram as últimas vinte encomendas em processing?
• A loja está acessível com as chaves que emitimos?

São as perguntas que aparecem nos stand-ups de integração ERP. São também as perguntas que não exigem acesso de escrita.

#Instalar e configurar

#Pré-requisitos

• Node.js 18 ou mais recente
• Uma loja WooCommerce em HTTPS
• Capacidade de criar chaves de API REST com permissão Read

#Instalação

npm install -g @wppoland/woocommerce-mcp
# ou one-shot:
npx @wppoland/woocommerce-mcp

A partir do código-fonte:

git clone https://github.com/wppoland/woocommerce-mcp.git
cd woocommerce-mcp
npm install
npm run build

#Variáveis de ambiente

Crie as chaves em WooCommerce → Definições → Avançado → REST API → Adicionar chave. Permissão: Read. Se alguém lhe entregar Read/Write “por precaução”, recuse. O pacote não precisa de scopes de escrita, e guardar scopes de escrita não usados é um incidente à espera de um portátil comprometido.

O search_posts funciona contra a API REST pública do WordPress sem chaves Woo. Isso é útil para agentes de conteúdo; continua a não ser razão para expor cookies de admin ao anfitrião MCP.

#Esboço Claude Desktop / Cursor

Registe um servidor stdio que execute o binário com as três variáveis de ambiente. As formas exatas de JSON variam com a versão do cliente; o invariante é: stdio, env injetado pelo anfitrião, sem segredos no transcript do chat.

Depois de ligar, faça uma pergunta falsificável: “Qual é o stock do SKU X?” Se o agente inventar um número sem chamada de ferramenta, o cliente não está realmente ligado. Se chamar list_products ou get_product e devolver o valor da loja, o teste de fumo está feito.

#Exemplo de fragmento Claude Desktop

Os formatos de config do cliente mudam; trate isto como forma, não como contrato eterno:

{
  "mcpServers": {
    "woocommerce-mcp": {
      "command": "woocommerce-mcp",
      "env": {
        "WP_URL": "https://shop.example.com",
        "WC_CONSUMER_KEY": "ck_replace_me",
        "WC_CONSUMER_SECRET": "cs_replace_me"
      }
    }
  }
}

Prefira um caminho completo para o binário a partir de npm root -g se o PATH da shell dentro da app desktop for mais estreito do que o PATH do terminal. O Cursor e outros anfitriões usam padrões semelhantes de stdio + env.

#Resolução de problemas de instalação

Se npm view @wppoland/woocommerce-mcp version devolver 404 enquanto npm access ainda lista o pacote, está no estado de stub partido que atingimos na 0.1.0. Incremente a versão, remova registry.npmjs.org/:_auth legado de ~/.npmrc se existir, e publique de novo. Não diga aos clientes da loja para instalar uma versão que não consegue npm pack.

#Modelo de segurança (em linguagem clara)

1. As chaves ficam no anfitrião MCP, não na loja como plugin e não nos pesos do modelo.
2. Permissão Read apenas na chave WooCommerce.
3. HTTPS apenas para WP_URL.
4. Trate a máquina do cliente MCP como produção se tiver chaves live - o mesmo critério de um secret store de CI.
5. Rode as chaves quando um portátil sai da empresa ou termina um contrato de freelancer.

O MCP não resolve autenticação por magia. O tratamento mais longo está em integração MCP e IA. Para este pacote, o default conservador é stdio local com chaves Read, não um endpoint HTTP MCP público na internet aberta.

#Notas de ameaça que aparecem em revisões reais

• Roubo de portátil: chaves Read vazam metadados de catálogo e de encomendas. Em Portugal isso continua a ser relevante para o RGPD (e para a CNPD). Encripte o disco, use chaves de curta duração para demos, revogue no offboarding.
• Injeção de prompt via descrições de produto: um título de produto malicioso não faz este pacote escrever, mas pode orientar a fala do modelo. Mantenha cópia de catálogo não confiável fora de automações de alto risco sem humano no ciclo.
• Confused deputy em anfitriões MCP partilhados: um perfil Claude Desktop com chaves da loja A e da loja B (por exemplo uma loja .pt e outra .es no mesmo grupo) é um acidente à espera de acontecer. Separe perfis ou máquinas.
• Fuga em logs: alguns anfitriões registam argumentos de ferramentas. Assuma que SKUs e ids de encomenda vão aparecer nos logs; configure retenção em conformidade.

Nada disto é razão para evitar MCP. São razões para tratar o anfitrião como produção.

#Onde isto encaixa em programas ERP e IA

O trabalho da WPPoland com clientes europeus liga com frequência WooCommerce a APIs de grossistas e ERPs. Os agentes entram nesse stack quando as equipas de operações querem respostas em linguagem natural sem abrir o wp-admin. O MCP só de leitura é a primeira fatia segura:

• Checks pré-sync: “Já estamos sem stock nos SKUs da campanha?”
• Auditorias pós-sync: “As encomendas de ontem batem certo com a contagem de faturas do ERP?”
• Ops de conteúdo: “Que artigos mencionam a nova coleção?” via search_posts

Quando precisar que os agentes proponham encomendas ou rascunhem reembolsos, sai deste pacote e constrói um servidor à medida com ferramentas de mutação explícitas, chaves de idempotência e gates de aprovação humana. Esse caminho é o desenvolvimento de servidores MCP mais a arquitetura em integração MCP e IA.

Para lojas já afogadas em sprawl de plugins ou dívida de temas feitos por IA, corrija Core Web Vitals e a verdade do inventário antes de adicionar agentes. O MCP não salva um TTFB de 1,8 s nem um catálogo que discorda do armazém em Alcochete ou da API do grossista.

#Como isto difere de experiências MCP hospedadas no WordPress

O WordPress.com e ecossistemas relacionados têm explorado superfícies MCP para alojamento gerido. Esses programas têm valor, e não são o mesmo artefacto que um servidor stdio self-hosted que aponta às suas chaves REST do WooCommerce. O MCP self-hosted mantém credenciais e tráfego na infraestrutura que escolhe. O MCP hospedado mantém a conveniência nos termos do anfitrião. Escolha de propósito; não assuma paridade de funcionalidades.

O WordPress Playground MCP é outro eixo útil para demos no browser, mas não substitui um servidor apontado à loja de produção. Glama e diretórios MCP semelhantes podem indexar o repo GitHub ou a entrada do registry. Trate diretórios de terceiros como descoberta, não como fronteira de segurança. A fonte de verdade para instalação continua a ser npm + GitHub + o nome oficial no MCP Registry.

#Comparação: pacote open-source vs MCP à medida

#Notas de publicação para maintainers

Se fizer fork ou publicar o seu próprio servidor MCP:

1. Coloque mcpName em package.json a coincidir com o namespace do registry (para auth GitHub: io.github.<org>/<name>).
2. Mantenha a description em server.json com 100 caracteres ou menos - o registry oficial rejeita strings mais longas com HTTP 422.
3. Use o binário mcp-publisher dos releases modelcontextprotocol/registry, não um pacote npm aleatório chamado publisher.
4. Prefira nomes npm sob um @scope que controla; nomes sem prefixo podem ficar permanentemente bloqueados após unpublish.

Aprendemos o limite da description da forma difícil na primeira tentativa de publish no registry. Validar com mcp-publisher validate antes de publish poupa uma ida e volta.

#Checklist operacional

• @wppoland/[email protected] (ou mais recente) instalado
• A chave WooCommerce é só Read
• WP_URL é HTTPS e corresponde à loja a que as chaves pertencem
• O cliente usa stdio (ou outro transporte que endureceu de propósito)
• O teste de fumo usa um SKU real e um intervalo de datas real
• Os segredos não são colados em tickets ou logs de chat
• A equipa sabe que este pacote não reembolsa nem repõe stock - escale para humanos / ERP para escritas

#Ligações internas do cluster

• Arquitetura e governação: Integração MCP e IA
• Serviço comercial: Desenvolvimento de servidores MCP
• Comércio e sync: Integração WooCommerce ERP
• Contexto de produto: Programador de WooCommerce
• Estratégia de plugin: Servidor MCP no plugin WordPress
• Demos no browser: WordPress Playground MCP
• Adoção no radar: Tech Radar: Anthropic MCP

#Notas de prática a partir de trabalho com clientes

Numa loja ibérica com Multibanco e MB Way (catálogo na casa dos milhares de SKUs, preços B2B no ERP), a demo que convenceu operações não foi um widget de chat na montra. Foi o Claude Desktop no portátil de ops a responder, antes do envio da newsletter: “quais SKUs da campanha já estão a zero?”. A demo passou a revisão de segurança só porque o MCP não podia “corrigir” o stock quando o modelo inventava uma escrita.

Num sync com um grossista português de peças (o mesmo padrão do nosso caso de integração WooCommerce com API de grossista), o pedido perigoso foi “marca estas como concluídas se parecerem pagas.” É exactamente a classe de ferramenta que este pacote open-source se recusa a oferecer. O agente pode listar encomendas em processing; um humano ou um job dedicado no ERP conclui-as.

Se a loja ainda usa application passwords com capacidades totais para “scripts temporários”, rode-as antes de apontar qualquer anfitrião MCP à produção. Chaves Read para este servidor são baratas de emitir e baratas de revogar - e encaixam melhor no RGPD do que cookies de sessão de admin partilhados num portátil de freela.

Em conversas pós-WordCamp Porto e em revisões com equipas de e-commerce em Lisboa, o padrão repetido é o mesmo: as operações querem perguntas de stock em linguagem natural às 08h30, antes da abertura do armazém. Querem também que o agente não possa tocar em estados de encomenda quando alguém cola um CSV de “urgentes” no chat. O pacote open-source cobre o primeiro desejo e bloqueia o segundo por desenho.

#O que não faremos na v0.x

• Sem ferramentas de escrita no branch default open-source.
• Sem plugin obrigatório na loja.
• Sem afirmar que o MCP substitui a REST do WooCommerce para integrações de parceiros.
• Sem preços específicos para trabalho de implementação - os projetos têm orçamento individual através de desenvolvimento de servidores MCP.

Pedidos de funcionalidade que cabem no mandato só de leitura (resumo de reembolsos, status de cupões, lookup de cliente sem dumps de PII) são conversa aberta no GitHub. Pedidos do tipo “só adiciona update_product” serão fechados com um apontador para o guia de build à medida.

#Medir se o caminho do agente vale a pena

Antes de expandir para além das ferramentas só de leitura, meça três coisas durante duas semanas:

1. Com que frequência humanos abrem o wp-admin só para responder a uma pergunta de stock ou encomenda. Se essa contagem for perto de zero, o MCP é novidade. Se for diária, as ferramentas de leitura pagam-se em atenção.
2. Com que frequência essas respostas discordam do ERP. O MCP mostra a verdade do WooCommerce, não a do armazém. Se divergirem, corrija o sync primeiro (integração WooCommerce ERP).
3. Com que frequência alguém pede ao agente para mudar estado. Essa frequência é o sinal de roadmap para um servidor mutante à medida - não uma razão para enfraquecer este pacote.

Programas GEO e AEO importam-se com respostas citáveis e estruturadas. Uma chamada de ferramenta MCP que devolve stock é mais fiável do que um modelo a adivinhar a partir de HTML scraped. Emparelhe o caminho do agente com entidades on-site e schema FAQ nas páginas comerciais para que sistemas de IA públicos e agentes privados não inventem histórias de produto diferentes.

Se já está a enviar um servidor MCP dentro de um plugin WordPress como fosso de produto, leia o nosso texto sobre porque um servidor MCP no plugin é a jogada de IA que sobrevive. Este pacote npm é o outro lado da mesma tese: superfície tipada, âmbito mínimo, sem chatbox cosmética no admin.

#Conclusão

O @wppoland/woocommerce-mcp é a menor superfície MCP útil em que confiamos à frente de uma loja WooCommerce live: cinco ferramentas de leitura, REST oficial por baixo, MIT, publicado no npm e no MCP Registry. Instale-o quando os agentes precisam de factos da loja. Construa um servidor à medida quando os agentes precisam de ações na loja.

Comece aqui: https://www.npmjs.com/package/@wppoland/woocommerce-mcp - depois ligue chaves Read, faça uma pergunta de fumo, e mantenha as escritas fora do caminho do agente até o programa estar pronto para elas.