pptx-mcp-server

Servidor MCP (stdio) que converte um arquivo HTML — escrito inteiramente pela LLM chamadora — em um PowerPoint (.pptx) nativo e editável. O servidor nunca gera nem embute nenhuma imagem/screenshot do slide inteiro; ele só usa um Chromium headless para medir o layout real (posições, fontes, cores) do HTML e converte o que foi marcado em objetos de verdade do PPTX (caixas de texto, formas, imagens).

Como funciona

1. A LLM escreve tudo. Todo o design, conteúdo e HTML/CSS (e imagens locais, se houver) são escritos pela LLM chamadora diretamente no workspace do usuário — o servidor não desenha, não escolhe layout, não tem opinião de design. Ele só converte.
2. Contrato de marcação. Cada slide é um elemento HTML com data-pptx-slide; dentro dele, qualquer elemento com data-pptx="text", data-pptx="shape" ou data-pptx="image" vira um objeto real no .pptx. Tudo que não tem data-pptx é só andaime de layout (divs de flexbox, grid, etc.) e é ignorado na conversão. Veja a tool get_pptx_authoring_guide para o contrato completo, com exemplo.
3. Conversão. O servidor abre o HTML num Chromium headless (só para ler getBoundingClientRect()/getComputedStyle() de cada elemento marcado — nenhum screenshot é tirado) e usa esses dados para montar o .pptx via pptxgenjs: texto vira caixa de texto editável, formas viram retângulos/retângulos arredondados com fill/borda reais, imagens viram objetos de imagem nativos.

Tools expostas

• get_pptx_authoring_guide() — devolve o guia completo de como escrever o HTML (o contrato data-pptx-slide/data-pptx, o que cada tipo lê de CSS, o que não é suportado, e orientações de design não-restritivas). Chame antes de escrever qualquer HTML — a conversão depende desse contrato; HTML sem essas marcações vira um .pptx vazio.
• list_pptx_templates() — lista os templates salvos no Template Studio (id, nome, descrição, paleta e layouts disponíveis). Chame antes de desenhar qualquer apresentação: se houver um template salvo, use-o em vez de inventar um visual novo.
• get_pptx_template({ id }) — devolve um template completo: a paleta, as fontes, a grade e, para cada layout, o HTML pronto com os slots a preencher.
• convert_html_to_pptx({ htmlPath, outputPath? }) — a tool que entrega o arquivo. Recebe o caminho absoluto de um único arquivo HTML já escrito pela LLM, extrai os elementos marcados e grava o .pptx. Devolve o caminho salvo e, se houver, avisos sobre elementos que não converteram bem (tamanho zero, imagem não encontrada, slide com tamanho diferente do primeiro).

Resolução de outputPath

1. Caminho absoluto informado → usado diretamente.
2. Caminho relativo ou omitido → tenta a primeira root declarada pelo cliente MCP (se ele suportar o recurso roots do protocolo).
3. Se o cliente não suportar roots → usa a variável de ambiente PPT_MCP_OUTPUT_DIR, se definida, ou ~/Documents/PPT-MCP como último fallback.

Template Studio

Um portal local de arrastar-e-soltar para desenhar a identidade visual das apresentações: paleta, fontes, grade e os layouts de slide. Ele não edita conteúdo — o conteúdo é a LLM que escreve, preenchendo os slots que você marcou no template.

npx pptx-mcp-server studio   # ou, no repositório local: npm run studio

O comando imprime uma URL e abre o navegador. Sem argumentos, o mesmo binário continua sendo o servidor MCP stdio de sempre, então nada muda para os clientes MCP.

Segurança: o servidor escuta apenas em 127.0.0.1, numa porta aleatória, e exige um token gerado a cada execução (vai na URL). Nada é exposto na rede.

Onde ficam os templates: ~/.pptx-mcp/templates/<slug>/, um template.json por pasta mais os assets/ enviados. Aponte para outro lugar com a variável de ambiente PPTX_MCP_TEMPLATES_DIR. Os templates embutidos aparecem como somente leitura — duplique um para começar.

Exportar amostra .pptx: gera um .pptx com um slide por layout, passando pelo mesmo pipeline de conversão de sempre, para você conferir no PowerPoint que o texto continua editável e as posições batem. O arquivo cai na mesma pasta de saída das conversões (veja "Resolução de outputPath").

O fluxo completo:

1. Você desenha o template no studio e salva.
2. A LLM chama list_pptx_templates() e escolhe um.
3. Chama get_pptx_template({ id }) e recebe o HTML de cada layout com os slots.
4. Preenche os slots com o conteúdo real e grava um arquivo HTML.
5. Chama convert_html_to_pptx({ htmlPath }) e entrega o .pptx.

Uso

npm install   # também baixa o Chromium do Playwright (postinstall)
npm run build
npm start     # inicia o servidor MCP via stdio

Configuração nos principais harnesses/clientes MCP

O pacote está publicado no npm como pptx-mcp-server, então na maioria dos clientes basta apontar command: npx, args: ["-y", "pptx-mcp-server"]. A env var PPT_MCP_OUTPUT_DIR é opcional (ver Resolução de outputPath); troque C:\caminho\padrao\de\saida pela pasta que preferir.

Claude Code

claude mcp add pptx-mcp-server -e PPT_MCP_OUTPUT_DIR=C:\caminho\padrao\de\saida -- npx -y pptx-mcp-server

Ou editando .mcp.json (projeto) / config de usuário diretamente — mesmo formato JSON do bloco "Claude Desktop / Cursor" abaixo.

Claude Desktop

Edite claude_desktop_config.json:

{
  "mcpServers": {
    "pptx-mcp-server": {
      "command": "npx",
      "args": ["-y", "pptx-mcp-server"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}

Cursor

Mesmo formato do Claude Desktop, em ~/.cursor/mcp.json (global) ou .cursor/mcp.json (projeto):

{
  "mcpServers": {
    "pptx-mcp-server": {
      "command": "npx",
      "args": ["-y", "pptx-mcp-server"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}

OpenAI Codex CLI

Adicione em ~/.codex/config.toml (ou .codex/config.toml do projeto):

[mcp_servers.pptx-mcp-server]
command = "npx"
args = ["-y", "pptx-mcp-server"]
env = { PPT_MCP_OUTPUT_DIR = "C:\\caminho\\padrao\\de\\saida" }

Google Antigravity (CLI agy / IDE)

Antigravity 2.0, a IDE e a CLI compartilham a mesma config, em ~/.gemini/config/mcp_config.json (ou .agents/mcp_config.json no workspace). Mesmo formato mcpServers/command/args de cima. Reinicie o Antigravity depois de editar.

VS Code (GitHub Copilot Chat, modo agente)

Crie/edite .vscode/mcp.json no projeto — repare que o VS Code usa a chave servers (não mcpServers) e exige "type": "stdio":

{
  "servers": {
    "pptx-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "pptx-mcp-server"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}

GitHub Copilot CLI

Via wizard interativo (/mcp add dentro do copilot) ou editando ~/.copilot/mcp-config.json:

{
  "mcpServers": {
    "pptx-mcp-server": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "pptx-mcp-server"],
      "tools": ["*"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}

Windsurf

Mesmo formato mcpServers/command/args, em ~/.codeium/windsurf/mcp_config.json.

Zed

Em settings.json (~/.config/zed/settings.json no macOS/Linux, %APPDATA%\Zed\settings.json no Windows), a chave é context_servers e servidores customizados precisam de "source": "custom":

{
  "context_servers": {
    "pptx-mcp-server": {
      "source": "custom",
      "command": "npx",
      "args": ["-y", "pptx-mcp-server"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}

Outros clientes

Quase todo cliente MCP stdio segue o mesmo formato básico — uma entrada com command: "npx" e args: ["-y", "pptx-mcp-server"], variando só a chave de agrupamento (mcpServers, servers, context_servers) e o caminho do arquivo de config. Consulte a documentação do cliente específico se ele não estiver nesta lista.

Rodando localmente (sem publicar/instalar via npm)

Durante desenvolvimento, ou se preferir não depender do registro npm, aponte command direto pro build local em vez de npx:

{
  "mcpServers": {
    "pptx-mcp-server": {
      "command": "node",
      "args": ["C:\\Projetos\\mcps\\ppt\\dist\\server.js"],
      "env": {
        "PPT_MCP_OUTPUT_DIR": "C:\\caminho\\padrao\\de\\saida"
      }
    }
  }
}