@creativeproject/creative-plann-mcp

Servidor MCP do Creative Plann. Conecta uma IA (Claude Code, Codex, Cursor) ao seu planejamento de redes sociais: ela lê o calendário, cria posts, escreve briefing e roteiro, e move os cards do fluxo.

Instalação

Não precisa instalar nada — o cliente baixa o pacote sob demanda.

Claude Code

claude mcp add creative-plann \
  -e CREATIVE_PLANN_TOKEN=seu_token \
  -- npx -y @creativeproject/creative-plann-mcp

Outros clientes

{
  "mcpServers": {
    "creative-plann": {
      "command": "npx",
      "args": ["-y", "@creativeproject/creative-plann-mcp"],
      "env": { "CREATIVE_PLANN_TOKEN": "seu_token" }
    }
  }
}

Token

Gere no menu da conta (avatar no topo) → API e IA. O token define:

• papel — de leitor a admin, nunca acima de quem o criou;
• empresas — todas, ou apenas as que você escolher;
• permissão de publicar — desligada por padrão.

O valor aparece uma única vez: guardamos apenas o hash. Se vazar, revogue e gere outro — leva um clique, e revogar um token não afeta os demais.

Variáveis de ambiente

| Variável | Obrigatória | Descrição | | --- | --- | --- | | CREATIVE_PLANN_TOKEN | sim | Token gerado na aplicação. | | CREATIVE_PLANN_URL | não | Base da instância. Padrão: https://plann.creativeproject.com.br. |

Publicar não é automático

Por padrão o token não publica. A IA planeja, escreve, organiza e agenda a data — mas mover o post para publicação exige uma pessoa na interface.

Isso é deliberado: publicar não tem desfazer. Um horário ou um texto errado vai ao ar no perfil do cliente, e nenhuma correção posterior desfaz quem já viu. Quando quiser automação completa, marque "pode publicar" ao gerar o token.

Anotações de comportamento

Cada ferramenta declara ao cliente MCP se apenas lê, se altera, e se é destrutiva. É o que permite ao cliente auto-aprovar list_posts e pedir confirmação em delete_post, set_stage e set_status — as três que apagam trabalho ou disparam publicação.

São hints de interface, não fronteira de segurança: a autorização real está no servidor, ligada ao papel e ao escopo do token.

Ferramentas

Contexto — whoami, list_companies, list_accounts, describe_vocabulary, list_members, list_media, list_campaigns, create_campaign

Visão do trabalho — get_board, get_calendar, list_posts, get_post, get_post_history

Criação e edição — create_post, update_post, schedule_post, set_stage, set_status, comment_on_post, delete_post

Comece por whoami: ele diz quais empresas o token alcança e o que ele pode fazer. Depois list_accounts, porque cada rede aceita formatos diferentes, com limites próprios de texto e de mídia.

Dois eixos independentes

O mesmo post tem etapa e status, e eles não são a mesma coisa:

• etapa (set_stage) é o fluxo editorial no Kanban: IDEA → BRIEFING → SCRIPT → PRODUCTION → INTERNAL_REVIEW → CLIENT_REVIEW → APPROVED_STAGE → READY;
• status (set_status) é o ciclo de publicação: DRAFT → IN_REVIEW → APPROVED → SCHEDULED → PUBLISHED.

PUBLISHING, PUBLISHED e FAILED são escritos pelo motor de publicação e não podem ser definidos pela API — deixá-los editáveis faria o histórico mentir.

Horários

Datas de trabalho são sempre locais à empresa, no formato "2026-09-01T10:30" — sem Z, sem offset. Cada empresa tem seu fuso, e a conversão acontece no servidor.

As respostas trazem os dois: { "utc": "...", "local": "..." }.

Um post, várias redes

Um post tem um conteúdo e vários destinos, cada um com seu formato. O mesmo material pode sair como Reel no Instagram, vídeo no Facebook e artigo no LinkedIn — com legenda própria por rede quando fizer sentido:

{
  "company": "minha-empresa",
  "contentKind": "VIDEO",
  "caption": "Legenda base para todas as redes.",
  "targets": [
    { "socialAccountId": "...", "format": "REEL" },
    { "socialAccountId": "...", "format": "VIDEO" },
    {
      "socialAccountId": "...",
      "format": "LINKEDIN_ARTICLE",
      "title": "Título do artigo",
      "body": "<p>Corpo longo, só no LinkedIn.</p>"
    }
  ]
}

Desenvolvimento

npm install
npm run build      # compila e marca o executável
npm test           # testes do cliente e contrato das ferramentas
npm run typecheck  # inclui os testes

CREATIVE_PLANN_URL aponta para outra instância — é como se testa contra um servidor local.

O executável (cli.ts) é separado da biblioteca (index.ts): importar o pacote não inicia servidor nem toma o stdio do processo.

Licença

MIT — veja LICENSE.