@polozi/social-mcp

Conector do Polozi Social: publica no Instagram da sua empresa direto do chat, pelo Claude Code ou pelo Codex.

Você conecta a conta uma vez, no navegador. Depois é conversa: "monta um post com essa foto e essa legenda" → você lê → você aprova → publica.

Feito para os alunos do Mestre das IAs.

Instalar

Precisa de Node 20 ou mais novo.

Claude Code

claude mcp add --scope user polozi-social -- npx -y @polozi/social-mcp@latest

Codex

codex mcp add polozi-social -- npx -y @polozi/social-mcp@latest

Reinicie o cliente depois de instalar — as tools só aparecem em sessão nova.

Conectar (uma vez por máquina)

Peça no chat: "conecta meu Instagram". O conector responde com duas coisas:

Abra:   https://publicar.polozi.pro/conectar
Codigo: K7P4-9RTM

Abra o endereço no navegador, entre com seu login e digite o código. Depois peça "conecta meu Instagram" de novo — ele termina o pareamento e guarda a chave.

O código nunca vem dentro do link, e isso é de propósito: link pronto para clicar é o caminho mais fácil de golpe. Se alguém te mandar um endereço já com o código dentro, não é nosso.

Sua conta do Instagram precisa ser profissional (comercial ou criador).

O que dá para pedir

| tool | o que faz | |---|---| | conectar_instagram | pareia esta máquina (e, rodando de novo, troca a chave dela) | | status_conexao | qual conta está conectada | | limite_restante | dá para publicar agora? | | criar_rascunho | sobe uma foto e monta o post — não publica | | criar_carrossel | sobe de 2 a 10 fotos, na ordem, e monta um carrossel — não publica | | criar_story | sobe uma foto e monta um story (sem legenda, some em 24h) — não publica | | aprovar_rascunho | registra que você leu e aprovou aquele post exato | | publicar | publica de verdade | | status_publicacao | em que pé está um post | | desconectar_instagram | mostra como desconectar (quem clica é você, no painel) |

Desconectar não é feito pelo chat. Retirar a autorização apaga o token do Instagram: é decisão sua, no painel, logado.

Marcar pessoas e postar junto

As três ferramentas de montar post aceitam, opcionalmente:

• marcacoes — marcar perfis na foto. Em post e carrossel a marcação precisa de uma posição na foto: diga do seu jeito ("no canto de baixo, à esquerda") e o chat converte. No carrossel, diga também em qual foto (da 1ª à 10ª). No story a posição é opcional. Quem é marcado recebe notificação quando o post sai.
• colaboradores — até 3 perfis que aparecem como autores do post (post e carrossel; story não aceita). Cada um recebe um convite e só vira coautor depois de aceitar.

Marque e convide só quem você pediu. O rascunho mostra quem vai ser marcado e convidado antes de você aprovar.

Onde a chave fica

A chave pk_ig_... é gravada em credenciais/.env do seu projeto, na variável POLOZI_SOCIAL_API_KEY, com permissão 600. Se você rodar fora de um projeto, ela vai para ~/.polozi/social.env.

O conector também registra o nome da variável em capacidades/CONEXOES.md e em credenciais/.env.example — nunca o valor, como manda o protocolo Empresa IA.

⚠️ Confira que credenciais/.env está no seu .gitignore. O conector avisa se não estiver: chave em repositório público é chave revogada.

Perdeu a chave, trocou de máquina ou quer rotacionar? Rode conectar_instagram de novo. A chave antiga daquela máquina morre no mesmo instante.

Limites que valem conhecer antes de tentar

• Foto JPEG até 8 MB. PNG e WebP são recusados pelo Instagram.
  • post e carrossel: entre 4:5 (retrato) e 1.91:1 (paisagem);
  • story: até 9:16 (retrato alto), que é o formato recomendado.
• Carrossel: de 2 a 10 fotos — é o limite da API (o app do Instagram deixa mais, mas pelo conector são 10). O Instagram recorta todas pela proporção da primeira, então use fotos com a mesma proporção.
• Story não tem legenda e some do perfil em 24h.
• Legenda até 2200 caracteres.
• Conta nova publica pouco. A cota do Instagram cresce com a audiência, então conta sem seguidores começa quase zerada e é normal bater o limite no primeiro dia. Pergunte limite_restante antes de montar o post.
• Post publicado não volta. A API do Instagram não apaga post — só dá para apagar na mão, pelo app.
• Existe uma chave geral do serviço: quando ela está desligada, dá para montar e aprovar, mas não para publicar.

O que este conector não garante

Num CLI agêntico, o modelo pode chamar montar → aprovar → publicar em sequência sem você ler nada no meio. A separação em três passos deixa rastro auditável (dá para provar depois o que foi aprovado pela tela e o que passou pelo chat), e o publicar exige uma confirmação literal — mas isso não é uma trava técnica, e não vendemos como se fosse.

Quem trava de verdade é o servidor: chave geral, cota, intervalo entre posts, rampa dos primeiros dias e o consentimento. Do seu lado, o que protege é o prompt de permissão do seu cliente MCP: mantenha a confirmação ligada para as tools de escrita.

E uma coisa o conector nunca faz: escrever legenda por você. O texto é sempre o que você escreveu ou aprovou.

Variáveis de ambiente (opcionais)

| variável | para quê | |---|---| | POLOZI_SOCIAL_API_KEY | usar uma chave sem gravar em disco (tem prioridade sobre os arquivos) | | POLOZI_SOCIAL_API | apontar para outro servidor (desenvolvimento) | | POLOZI_HOME | trocar o diretório de estado, que por padrão é ~/.polozi | | POLOZI_PAREAMENTO_ORCAMENTO_MS | quanto tempo conectar_instagram espera por chamada (padrão 50s). Diminua se o seu cliente tem timeout curto |

Dependências, sem maquiagem

Este pacote depende do SDK oficial de MCP (@modelcontextprotocol/sdk) e do zod. São duas dependências diretas, mas o SDK traz junto cerca de 93 pacotes transitivos. Preferimos o SDK oficial à compatibilidade improvisada com cada cliente, e por isso as versões aqui são cravadas (sem ^), com lockfile — mas o número está escrito aqui porque você merece saber o que entra na sua máquina.

Quando der erro

As mensagens vêm prontas do servidor, em português, e dizem o próximo passo. As mais comuns:

| mensagem | o que fazer | |---|---| | "Esta maquina ainda nao esta pareada" | rode conectar_instagram | | "A conta do Instagram desta chave nao esta mais conectada" | a conta mudou; rode conectar_instagram de novo | | "Esse conector e da versao X e o minimo hoje e Y" | npx -y @polozi/social-mcp@latest | | "A publicacao esta desligada no momento (chave geral)" | não é com você; tente mais tarde | | "Voce ja atingiu o limite de posts de hoje" | espere a virada do dia |

Suporte: https://publicar.polozi.pro/app