PostMCP AI

Publique e agende posts para LinkedIn, X, Facebook, Instagram, Threads, Bluesky e YouTube Shorts com uma única chave de API.

GitHubExperimente este MCPPatrocinado

Documentação

Servidor PostMCP AI Model Context Protocol (MCP)

Servidor oficial PostMCP AI Model Context Protocol (MCP). Conecte seus pipelines de publicação em redes sociais diretamente a assistentes de IA, aplicativos de desktop, fluxos de trabalho de IDE e ambientes web como Claude Desktop, Claude.ai, Cursor e ChatGPT Custom GPTs.

As plataformas suportadas incluem LinkedIn, X (Twitter), Facebook, Instagram, Threads, Bluesky e YouTube Shorts.

🚀 Recursos e Capacidades

🤖 15 Ferramentas Integradas: Workspaces, contas conectadas e a saúde de seus tokens, kits de marca, fila de posts, verificações pré-publicação, criar/agendar/reagendar/publicar/repetir/excluir e geração de imagens.
⚡ Modos de Transporte Duplos: Modo Stdio nativo (para aplicativos de desktop locais e IDEs) e modo HTTP Streamable (para serviços web, Claude.ai e conectores remotos).
🔑 Autenticação Flexível: Detecta automaticamente a chave de API a partir de variáveis de ambiente (POSTMCPAI_API_KEY), parâmetros de consulta de URL (?apikey=YOUR_KEY) ou cabeçalhos de autorização HTTP (x-api-key, Bearer token).
🗂️ Compatível com Múltiplos Workspaces: A chave de API carrega seu próprio workspace, então uma chave simples é suficiente. Para atuar em outro, cada ferramenta aceita um workspaceId opcional, também configurável por conexão (?projectId=..., x-project-id) ou por processo (POSTMCPAI_PROJECT_ID).
🤖 Compatível com ChatGPT Actions: Inclui gerador de especificação OpenAPI 3.0 integrado (/openapi.json) e endpoints REST (/api/tools/:name) para integração com ChatGPT Custom GPT.
🔒 Suporte a OAuth 2.0 e RFC 9728: Anuncia metadados do servidor de autorização PKCE para registro dinâmico e contínuo de clientes com Claude.ai.

📁 Arquitetura do Repositório

mcp-server/
├── bin/
│   └── cli.js            # Executable CLI entry point (Stdio / HTTP mode runner)
├── src/
│   ├── config.js         # Centralized configuration & environment loader
│   ├── client.js         # Backend API client, API key & workspace extraction
│   ├── platforms.js      # Platform limits, credit pricing & post cost helper
│   ├── tools/
│   │   ├── definitions.js# MCP tool JSON schemas & parameter specifications
│   │   ├── handlers.js   # MCP tool execution handlers
│   │   └── index.js      # Tool definitions aggregator
│   ├── server.js         # MCP Server instance factory
│   ├── routes/
│   │   ├── oauth.js      # OAuth 2.0 & RFC 9728 discovery endpoints
│   │   ├── openapi.js    # OpenAPI 3.0 schema & ChatGPT REST endpoints
│   │   ├── mcpHttp.js    # MCP Streamable HTTP transport (/mcp)
│   │   └── health.js     # Health check & system metadata endpoints
│   ├── app.js            # Express application factory
│   └── index.js          # Main library entry point
├── index.js              # Executable wrapper script
├── package.json
└── README.md

⚙️ Configuração de Ambiente

Variável de Ambiente	Descrição	Valor Padrão
`POSTMCPAI_API_KEY`	Obrigatória. Sua chave de API secreta do painel do PostMCP AI.	`None`
`POSTMCPAI_API_URL`	Raiz da API de backend. Defina apenas para um backend auto-hospedado ou local.	`https://api.postmcpai.com`
`POSTMCPAI_PROJECT_ID`	Opcional. Substitui o workspace ao qual a chave de API está vinculada. Por sua vez, é substituído pelo `workspaceId` de uma chamada.	O workspace a partir do qual a chave de API foi emitida
`PORT`	Definir isso inicia o servidor no Modo HTTP Streamable Remoto.	`None` (Padrão: Modo Stdio)

🛠️ Referência de Ferramentas MCP

Cada ferramenta abaixo também aceita um workspaceId opcional (de list_workspaces) para atuar em um workspace específico.

Leitura

Nome da Ferramenta	Descrição	Obrigatório	Opcional
`get_user_info`	Usuário autenticado: plano, saldo de créditos, tokens de IA, workspace ativo e função.	—	`workspaceId`
`list_workspaces`	Todos os workspaces aos quais o usuário pertence, com IDs, funções e plataformas conectadas.	—	—
`get_connected_accounts`	Perfis sociais conectados com o `profileId` necessário para direcioná-los.	—	`workspaceId`
`get_account_health`	Conexões cujo token expirou ou está próximo de expirar e precisam ser reconectadas.	—	`workspaceId`
`list_brandings`	Kits de marca: tom, público, palavras-chave, imagens de estilo.	—	`workspaceId`
`list_posts`	Fila de posts, mais recentes primeiro, com status de entrega por perfil, paginação e contagens.	—	`status`, `page`, `limit`, `all`
`get_post`	Um post completo: quais perfis o receberam, URLs ao vivo e erros por perfil.	`id`	—

Escrita

Nome da Ferramenta	Descrição	Obrigatório	Opcional
`preflight_post`	Teste seco: limites de caracteres, perfis não conectados, mídia ausente, custo de créditos. Não publica nada.	`content`	`targetAccounts`, `platforms`, `mediaUrl`
`create_post`	Rascunho, agendamento ou publicação imediata de um post para perfis nomeados. Cada perfil se torna seu próprio post com seu próprio ID.	`content`	`targetAccounts`, `variants`, `platforms`, `publishImmediately`, `scheduleDate`, `scheduleTime`, `timezone`, `mediaUrl`
`publish_post_now`	Publica um post existente imediatamente; também tenta novamente um post com falha, pulando perfis já entregues.	`id`	—
`update_post`	Atualiza conteúdo, perfis de destino, agendamento, mídia ou status.	`id`	`content`, `targetAccounts`, `platforms`, `scheduleDate`, `scheduleTime`, `timezone`, `mediaUrl`, `status`
`reschedule_post`	Move um post para um novo horário, mantendo o texto e os destinos. Reativa posts com falha e rascunhos.	`id`, `scheduleDate`, `scheduleTime`	`timezone`
`reset_stuck_post`	Libera um post travado no meio da publicação para que possa ser tentado novamente. Perfis já entregues mantêm seu estado.	`id`	`force`
`delete_post`	Cancela e exclui um post agendado ou com falha.	`id`	—
`generate_image`	Gera uma imagem para o post e retorna sua URL hospedada para `mediaUrl`. Consome tokens de IA.	`prompt`	`brandingId`, `styleImageUrl`

Lote

Nome da Ferramenta	Descrição	Obrigatório	Opcional
`multicall`	Executa até 20 das ferramentas acima em uma única solicitação, em ordem. Os nomes das ferramentas são validados antes de qualquer execução, então um erro de digitação não pode deixar metade de um lote gravado. Não pode ser aninhado.	`calls`	`stopOnError`, `workspaceId`

{
  "calls": [
    { "id": "img", "tool": "generate_image", "arguments": { "prompt": "launch banner" } },
    {
      "tool": "create_post",
      "arguments": {
        "content": "We shipped it 🚀",
        "targetAccounts": [
          { "platform": "linkedin", "profileId": "lin_7741903" },
          { "platform": "twitter", "profileId": "tw_1293847", "content": "We shipped it 🚀" }
        ],
        "scheduleDate": "2026-09-01",
        "scheduleTime": "10:00",
        "timezone": "Asia/Kolkata"
      }
    }
  ],
  "stopOnError": true
}

A resposta traz uma entrada por chamada — { id, tool, ok, result } ou { id, tool, ok: false, error } — além de contagens e, quando uma falha interrompe o lote, as chamadas que foram ignoradas.

Notas para clientes

Direcione perfis, não plataformas. targetAccounts envia apenas para os perfis nomeados; platforms distribui para todos os perfis conectados em cada plataforma.
Um post por perfil. create_post armazena um post separado para cada perfil direcionado, para que cada um possa ser editado, tentado novamente ou cancelado individualmente. Forneça texto por perfil por meio de targetAccounts[].content ou do mapa variants.
Sempre passe timezone quando o horário do relógio for importante. O backend usa UTC por padrão, então um post às 9:00 IST agendado sem fuso horário será publicado às 14:30 IST.
Créditos são cobrados por perfil entregue (X/Twitter custa 5, outros custam 1), além de uma sobretaxa única de 50 créditos quando o texto contém um link. preflight_post informa isso antes de você confirmar.

💻 Guias de Integração para Clientes

1. Claude Desktop App (Modo Stdio)

Adicione a configuração abaixo ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postmcpai": {
      "command": "npx",
      "args": ["-y", "@postmcpai/server"],
      "env": {
        "POSTMCPAI_API_KEY": "pmcp_sec_your_secret_api_key_here"
      }
    }
  }
}

2. Cursor IDE

Abra Cursor Settings -> Features -> MCP.
Clique em + Add New MCP Server.
Preencha os detalhes:
- Name: postmcpai
- Type: command
- Command: npx -y @postmcpai/server
Em Environment Variables, adicione:
- POSTMCPAI_API_KEY = pmcp_sec_your_secret_api_key_here
Clique em Save.

3. Claude.ai e Conectores Web Remotos (Modo HTTP Streamable / SSE)

Hospede este servidor em qualquer serviço de nuvem (Render, Railway, Fly.io, Vercel) ou faça um túnel para sua máquina local usando ngrok.

Iniciando no Modo HTTP:

export POSTMCPAI_API_KEY="pmcp_sec_your_secret_api_key_here"
export PORT=3000

npm run start:sse

Conectando ao Claude.ai:

Forneça sua URL MCP pública com sua chave de API anexada: https://your-hosted-domain.com/mcp?apikey=pmcp_sec_your_secret_api_key_here
O Claude.ai descobrirá os recursos das ferramentas por meio de /mcp e autenticará de forma contínua.
Essa URL é tudo o que você precisa: a chave está vinculada ao workspace a partir do qual foi emitida, então as ferramentas atuam nesse workspace sem precisar ser informadas. Para apontar a mesma chave para um workspace diferente, acrescente &projectId=YOUR_WORKSPACE_ID (ou envie um cabeçalho x-project-id); chamadas individuais de ferramentas ainda podem substituir qualquer um deles com workspaceId.

4. ChatGPT Custom GPTs (Ações REST)

Ao configurar uma Custom GPT Action, especifique a URL do seu servidor (por exemplo, https://your-hosted-domain.com).
Importe o esquema OpenAPI diretamente de: https://your-hosted-domain.com/openapi.json
Defina a Autenticação como API Key (Nome do Cabeçalho: Authorization ou x-api-key).

5. Uso Programático da Biblioteca Node.js

Você também pode usar @postmcpai/server como uma biblioteca em seus próprios backends Node.js:

import { createServer, createExpressApp, makeBackendRequest } from "@postmcpai/server";

// Create a standalone MCP Server instance
const mcpServer = createServer(() => process.env.POSTMCPAI_API_KEY);

// Or create an Express app with all remote routes attached
const app = createExpressApp();
app.listen(3000);

🧪 Testes Locais e Desenvolvimento

# Clone the repository
git clone https://github.com/postmcp/postmcp-mcp-server.git
cd postmcp-mcp-server

# Install dependencies
npm install

# Start in Stdio Mode
npm start

# Start in HTTP Mode with hot reload
npm run dev