mcp-ml-vendedor

Servidor MCP para o vendedor do Mercado Livre usar pelo Claude Desktop ou pelo Claude Code: lê e edita os próprios anúncios pela API oficial, com login OAuth. Seis usos: Ads, compatibilidade de autopeças, raio-x do anúncio, ficha técnica, melhoria de foto e SEO de título.

Começa em modo só leitura. As ferramentas que alteram a conta só aparecem quando você libera.

Instalação

Precisa só do Claude Desktop ou do Claude Code instalado. O instalador traz o resto (inclusive o Node.js, numa pasta só dele), registra o servidor nos dois (no que estiver instalado) e no fim abre o login do Mercado Livre no navegador.

Windows — abra o PowerShell e cole:

irm https://www.traveoone.com.br/mcp.ps1 | iex

Mac — abra o Terminal e cole:

curl -fsSL https://www.traveoone.com.br/mcp.sh | sh

Na primeira vez, o navegador abre o site da TraveoOne: entre com o seu e-mail (chega um código de 6 números) e clique em Autorizar este computador. Em seguida ele vai sozinho para o Mercado Livre: entre com a conta da loja (a principal, não a de colaborador) e autorize. Seus computadores conectados (até 3) ficam em www.traveoone.com.br/conta. Depois feche e abra o Claude — no Claude Desktop, feche de verdade (Windows: ícone perto do relógio → Sair; Mac: Cmd+Q) — e peça, por exemplo:

• "mostra minha conta do Mercado Livre"
• "lista meus anúncios que precisam de compatibilidade"
• "faz o raio-x do MLB…"

Já tem Node.js 20+? Também dá para registrar direto e conectar a conta pelo próprio Claude:

claude mcp add --scope user mercadolivre -- npx -y @traveoone/mcp-ml-vendedor            # Mac
claude mcp add --scope user mercadolivre -- cmd /c npx -y @traveoone/mcp-ml-vendedor     # Windows

Depois de instalado

• Refazer o login: peça ao Claude "conecte minha conta do Mercado Livre".
• Várias contas (lojas): peça "conecte outra conta do Mercado Livre". Antes, saia da conta atual no site do Mercado Livre (ou abra o link numa janela anônima) — senão o navegador entra direto na conta que já está logada. As contas ficam todas conectadas e uma é a ativa: é nela que o Claude lê e edita. Para trocar: "use a conta LOJA_X"; para ver todas: "quais contas estão conectadas?"; para tirar uma: "desconecte a conta LOJA_X". Com duas ou mais contas, toda resposta diz de qual conta é. Cada janela do Claude tem a sua conta ativa, e a última escolhida vale quando o Claude abre de novo.
• Grupos de contas (ex.: um por cliente, para quem atende várias empresas): peça "coloque LOJA_A, LOJA_B e LOJA_C no grupo Cavallaro". A lista de contas passa a aparecer por grupo ("mostre as contas da Cavallaro" mostra só as dele) e toda resposta diz o grupo da conta ativa. Cada conta fica em um grupo só; para tirar: "tire a LOJA_B do grupo". Os grupos só organizam a lista — não mudam nada no Mercado Livre.
• Liberar a edição: peça ao Claude "libere a edição". Vale na hora, sem reabrir o Claude, e a escolha fica salva. Para voltar ao modo só leitura: "bloqueie a edição". O Claude pede sua permissão a cada alteração — não marque "sempre permitir" nas de edição. Toda alteração (e cada vez que a edição é liberada ou bloqueada) fica registrada em ~/.mcp-ml-vendedor/auditoria.log.
• Atualizar: rode o comando de instalação de novo.
• Desinstalar: claude mcp remove mercadolivre -s user; no Claude Desktop, tire o "mercadolivre" de claude_desktop_config.json (Configurações → Desenvolvedor → Editar configuração); e apague a pasta ~/.mcp-ml-vendedor.

Ferramentas

| Uso | Leitura | Edição (com ML_PERMITIR_EDICAO=true) | |---|---|---| | Contas | conectar_mercado_livre, listar_contas, usar_conta, desconectar_conta, agrupar_contas, tirar_do_grupo, configurar_edicao | — | | Anúncios | minha_conta, listar_anuncios, ver_anuncio | — | | Raio-x | raio_x, raio_x_lista | — | | Ficha técnica | ficha_tecnica | atualizar_ficha_tecnica | | Compatibilidade | compatibilidades, buscar_valores_veiculo, contar_veiculos | adicionar_compatibilidades, remover_compatibilidades | | Título | dados_para_titulo | mudar_titulo | | Fotos | diagnosticar_fotos, melhorar_foto | trocar_foto | | Ads | ads_campanhas, ads_do_anuncio, ads_anuncios_da_campanha | ads_mudar_anuncio, ads_criar_campanha, ads_mudar_campanha |

Regras que vêm do Mercado Livre e que o servidor respeita:

• Título não muda depois da 1ª venda (exceto loja oficial), nem quando o título é gerado pelo catálogo. dados_para_titulo avisa antes.
• Compatibilidades do catálogo do Mercado Livre aparecem só em resumo e não se editam pela API; as do vendedor, sim. Até 200 veículos por chamada — adicionar_compatibilidades confere antes.
• Fotos: melhorar_foto corrige no computador, sem IA e sem mexer no anúncio: fundo quase branco vira branco puro, recorta a sobra e centraliza em 1200×1200. Fundo colorido (foto de bancada) não é removido — só avisa. trocar_foto só envia arquivos da pasta de fotos (~/.mcp-ml-vendedor/fotos) e recusa anúncio com variações.
• Ads: exige Product Ads ativo na conta (Meu perfil > Publicidade). O orçamento diário que o Claude pode definir tem teto: ML_TETO_ORCAMENTO_DIARIO no .env (padrão 1000, na moeda do site).

Segurança

• Só leitura por padrão. Editar exige você pedir para liberar e a sua permissão em cada alteração. Enquanto a edição está bloqueada, as ferramentas que alteram anúncios recusam qualquer alteração — a trava fica no servidor, não depende do app.
• A senha do Mercado Livre nunca passa pelo servidor nem pelo Claude: o login é na página oficial.
• A chave secreta do app fica só no servidor de login (no site da Traveo One), nunca no seu PC. Os tokens das suas contas ficam só no seu PC (~/.mcp-ml-vendedor/contas/, um arquivo por conta); o servidor de login não guarda nada.
• trocar_foto não envia arquivo de fora da pasta de fotos (proteção contra pedido malicioso escondido, por exemplo, numa pergunta de comprador).

Para quem mantém o projeto

npm install
npx vitest run       # testes (no Windows, pela PowerShell — no Git Bash o Vitest pode falhar)
npm run cobertura    # testes com cobertura (mínimo 80%)
npx tsc --noEmit     # tipos
npm run build        # dist/

Peças:

• Pacote npm @traveoone/mcp-ml-vendedor (dist/, conta traveoone no npm, com 2FA). Publicar: suba a version no package.json e rode npm publish no seu terminal (pede o código do 2FA; o prepublishOnly compila e roda os testes antes).
• Servidor de login — src/servidorDeLogin/rotas.ts, testado aqui e copiado igual para o site em api/_lib/servidorDeLogin.ts (repositório TraveoOne, projeto traveo-one da Vercel); o api/mercadolivre/[acao].ts só liga a conferência do acesso. Variáveis e regras em docs/servidor-de-login.md.
• Acesso pela TraveoOne — só quem entrou no site (e-mail + código) e foi liberado usa o servidor de login. Fluxo, rotas e transição em docs/acesso-traveoone.md.
• Instaladores — instalador/mcp.ps1 e instalador/mcp.sh, copiados para public/ do site.

Desenvolvimento sem o servidor de login: ponha ML_CLIENT_ID, ML_CLIENT_SECRET e ML_REDIRECT_URI num .env nesta pasta. Com secret no .env, o login é direto com o Mercado Livre (npm run autorizar).

Estado do projeto, fatos da API e incertezas em aberto: HANDOVER.md. Cópias das páginas da documentação usadas: docs/referencia-api/.