Carbone

Servidor MCP universal de geração e conversão de documentos. Gere PDF/DOCX/XLSX a partir de modelos+JSON (faturas, contratos, relatórios), geração em lote, mais de 100 conversões de formato.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Carbone

Servidor MCP oficial da Carbone — Transforme assistentes de IA em especialistas em automação de documentos. Gere PDFs profissionais, faturas, relatórios e muito mais usando linguagem natural.

Dê ao Claude, ChatGPT e outros assistentes de IA o poder de:

🔄 Conversão de Documentos — Mais de 100 combinações de formatos (PDF, DOCX, XLSX, PNG, HTML, CSV…)
📄 Mecanismo de Templates — Gere documentos a partir de dados JSON com tags {d.field}
📚 Biblioteca de Templates — Envie, versione, categorize e gerencie templates reutilizáveis
🎨 Personalização de PDF — Preencha formulários PDF, adicione marcas d'água, senhas, criptografia, múltiplos mecanismos de conversão
🌍 Localização — Suporte a vários idiomas, conversão de moedas, tratamento de fusos horários
⚡ Geração em Lote — Crie centenas de documentos em uma única solicitação (assíncrono via webhook)

Instalação

Obtenha sua chave de API gratuita em account.carbone.io.

stdio — Claude Desktop, VS Code, Cursor, Claude Code e outros

Todos os clientes MCP compatíveis com stdio usam a mesma configuração:

{
  "mcpServers": {
    "carbone": {
      "command": "npx",
      "args": ["-y", "carbone-mcp"],
      "env": {
        "CARBONE_API_KEY": "your_api_key_here"
      }
    }
  }
}

Cliente	Arquivo de configuração
Claude Desktop (macOS)	`~/Library/Application Support/Claude/claude_desktop_config.json`
Claude Desktop (Windows)	`%APPDATA%\Claude\claude_desktop_config.json`
Cursor (global)	`~/.cursor/mcp.json`
Cursor (projeto)	`.cursor/mcp.json`
Claude Code	`claude mcp add carbone-mcp -e CARBONE_API_KEY=your_key -- npx -y carbone-mcp`

VS Code usa { "mcp": { "servers": { ... } } } em vez de { "mcpServers": { ... } } — o bloco de configuração interno é idêntico.

Após adicionar a configuração, reinicie o cliente e tente: "O que a Carbone pode fazer?"

HTTP — mcp.carbone.io (sem instalação local)

Conecte-se diretamente ao endpoint hospedado. Suportado por VS Code, Cursor, Claude Code e outros clientes que suportam transporte HTTP streamable.

{
  "mcp": {
    "servers": {
      "carbone": {
        "type": "streamable-http",
        "url": "https://mcp.carbone.io",
        "headers": {
          "Authorization": "Bearer your_api_key_here"
        }
      }
    }
  }
}

Autenticação: O endpoint HTTP atualmente requer uma chave de API da Carbone passada como token Bearer no cabeçalho Authorization. O suporte a OAuth2 (para Claude Desktop, Mistral, ChatGPT, Gemini e outros clientes) está planejado para uma versão futura.

Cursor usa { "mcpServers": { ... } } em vez de { "mcp": { "servers": { ... } } } — o bloco de configuração interno é idêntico.

Claude Desktop não suporta autenticação por token Bearer HTTP — use a opção stdio acima.

Docker — servidor HTTP auto-hospedado

docker run -d -p 3000:3000 \
  -e MCP_TRANSPORT=http \
  -e CARBONE_API_KEY=your_api_key_here \
  carbone/carbone-mcp

Conecte seu cliente MCP a http://your-host:3000 usando a configuração HTTP acima (substitua a URL).

Docker Compose — veja compose.yml:

CARBONE_API_KEY=your_key docker compose up -d

Claude Desktop com Docker (stdio) — O Claude Desktop não suporta transporte HTTP; use o modo stdio:

{
  "mcpServers": {
    "carbone": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "CARBONE_API_KEY=your_api_key_here",
               "-e", "MCP_TRANSPORT=stdio",
               "carbone/carbone-mcp"]
    }
  }
}

On-Premise — instância Carbone auto-hospedada

Se você executa Carbone on-premise, aponte o servidor MCP para sua instância — nenhuma chave de API é necessária:

# Docker (HTTP)
docker run -d -p 3000:3000 \
  -e CARBONE_BASE_URL=https://your-carbone-server.com \
  carbone/carbone-mcp

# stdio
CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp

Variáveis de Ambiente

Obrigatórias (modo stdio, API na nuvem):

CARBONE_API_KEY — Sua chave de API da Carbone (obtenha uma gratuitamente →). Não é necessária quando CARBONE_BASE_URL aponta para seu próprio servidor on-premise, ou ao executar em modo HTTP (os clientes fornecem sua própria chave via Authorization: Bearer).

Configuração opcional

Variável	Padrão	Descrição
`CARBONE_BASE_URL`	`https://api.carbone.io`	Substituição para ambientes auto-hospedados ou de staging. Quando definido para uma URL personalizada, `CARBONE_API_KEY` não é necessário.
`CARBONE_TIMEOUT`	`60000`	Tempo limite de solicitação em milissegundos (máx: 60000)
`CARBONE_MAX_FILE_BYTES`	`104857600`	Tamanho máximo (bytes) para um arquivo de entrada resolvido — caminho, URL ou base64 (padrão 100 MB)
`MCP_TRANSPORT`	`stdio`	Modo de transporte: `stdio` (padrão, para clientes de IA) ou `http` (para implantações auto-hospedadas)
`MCP_PORT`	`3000`	Porta do servidor HTTP (usada apenas quando `MCP_TRANSPORT=http`)
`MCP_PATH`	`/`	Caminho do endpoint HTTP (usado apenas quando `MCP_TRANSPORT=http`)
`MCP_MAX_BODY_BYTES`	`62914560`	Tamanho máximo do corpo da solicitação em bytes (padrão 60 MB, correspondente ao limite da Carbone Cloud)
`CARBONE_REQUIRE_CLIENT_AUTH_HEADER`	`false`	Somente modo HTTP — exige `Authorization: Bearer <key>` em cada solicitação. Deixe `false` apenas se você pretende um servidor de chave compartilhada: com um `CARBONE_API_KEY` de nível de servidor definido, solicitações sem chave Bearer usam essa chave como fallback, então qualquer pessoa que possa acessar a porta pode gastar essa conta Carbone. Defina como `true` para exigir que cada cliente traga sua própria chave. Irrelevante quando nenhuma chave de servidor está definida (ex.: on-premise)
`CARBONE_ALLOW_PRIVATE_NETWORK`	`false`	Permite que URLs fornecidas pelo usuário (templates, `data`, …) resolvam para endereços privados/internos. Desativado por padrão para bloquear SSRF (metadados de nuvem, `localhost`, RFC1918). Ative apenas em uma implantação confiável com hosts de template internos

Ferramentas Disponíveis

Operações de Documentos

Ferramenta	Descrição	Docs
`convert_document`	Converta documentos entre mais de 100 formatos sem armazenar um template	→
`render_document`	Gere documentos a partir de templates mesclando com dados JSON	→

Gerenciamento de Templates

Ferramenta	Descrição	Docs
`list_templates`	Navegue pela sua biblioteca de templates com filtros por categoria ou busca (as tags são retornadas por template, mas não são filtráveis no servidor)	→
`list_categories`	Liste todas as categorias de templates na sua conta	→
`list_tags`	Liste todas as tags usadas nos seus templates	→
`upload_template`	Armazene templates reutilizáveis com versionamento, categorização e metadados	→
`update_template_metadata`	Renomeie, categorize, marque, implante ou expire versões de templates	→
`delete_template`	Exclusão suave de templates (marcados para remoção, removidos após ~24h)	→
`download_template`	Baixe arquivos de template originais (DOCX, XLSX, PDF, etc.)	→

Descoberta

Ferramenta	Descrição	Docs
`get_api_status`	Verifique a saúde da API Carbone e a versão atual
`get_capabilities`	Veja todos os formatos suportados, recursos e exemplos

📖 Referência Completa da API → — Parâmetros detalhados, esquemas e exemplos

Saída e Entrega de Arquivos

Por padrão, um arquivo gerado ou convertido é retornado com base no seu tipo e transporte:

Saída	stdio (clientes locais)	HTTP (remoto / auto-hospedado)
Texto — HTML, TXT, CSV, MD, XML	texto inline	texto inline
Imagens inline — PNG, JPG, GIF, WEBP	imagem inline	imagem inline
Todo o resto — PDF, Office, ZIP, SVG…	salvo em um arquivo temporário, caminho retornado	retornado como anexo de download

Três parâmetros opcionais em convert_document e render_document (e outputPath / asAttachment em download_template) substituem isso:

Parâmetro	Efeito
`outputPath`	Somente stdio — salve a saída neste caminho local em vez de retorná-la inline (rejeitado no modo HTTP)
`asAttachment`	retorne os bytes como um anexo para download em qualquer formato, em vez de inline
`returnLink`	retorne a URL pública de download de uso único da Carbone em vez do arquivo — de curta duração e consumida pelo primeiro download, então entregue-a ao usuário em vez de buscá-la você mesmo (funciona em stdio e HTTP)

Claude Desktop: ele não consegue renderizar anexos binários inline (os trata incorretamente como imagens). Para PDFs e arquivos Office, use o caminho de arquivo temporário padrão do stdio, ou use returnLink para obter uma URL de download.

Casos de Uso Comuns

📄 Conversão de Documentos

"Convert this Word document to PDF: /path/to/contract.docx"
"Turn my Excel spreadsheet into CSV format"
"Convert this HTML page to a PNG image"
"Convert my Markdown README to PDF"
"Convert this PPTX to PNG — use OnlyOffice for best fidelity"
"Rasterize this PDF to PNG images — one per page"

💼 Finanças e Faturamento

"Generate an invoice using template T123 with: {customer: 'Acme Corp', total: 1500, items: [...]}"
"Generate invoices from the data in /data/invoices.json"
"Create 500 invoices from my billing data and bundle them in a ZIP"
"Generate a French invoice for my Paris client — use EUR currency and fr-fr locale"
"Render this monthly report for each client in clients.json and ZIP them all"
"Generate invoice-{d.id}.pdf for each row in my sales data"

⚖️ Jurídico e Conformidade

"Add a CONFIDENTIAL watermark to this contract before sending it"
"Convert this NDA to PDF/A format for long-term archiving"
"Generate a password-protected PDF — open password: 'secret123'"
"Create signed offer letters for each candidate using this DOCX template"
"Generate a compliance report with a DRAFT watermark, 20% opacity, rotated -45°"

👥 RH e Operações de Pessoas

"Create personalized onboarding documents for all 50 new employees in this JSON"
"Generate an employment contract for each person in new-hires.json"
"Build payslips for every employee in my payroll export"
"Create training certificates for everyone who passed this month"
"Fill out the performance review template with each employee's data"

🌍 Localização e Multilíngue

"Generate this invoice in French, German, and Spanish from the same template"
"Render the report with timezone America/New_York so dates show in Eastern time"
"Convert all prices from EUR to USD using today's exchange rates"
"Generate the contract in fr-fr locale so numbers use European formatting"

🔐 Segurança de PDF e Opções Avançadas

"Convert this DOCX to a password-protected PDF"
"Add a semi-transparent DRAFT watermark to every page"
"Generate a PDF/A-1b compliant version of this document for archiving"
"Export only pages 1–5 of this presentation as a PDF"
"Convert each slide of this PPTX to a separate PDF page"

📚 Gerenciamento de Templates

"Upload this invoice template and tag it 'sales' and 'finance'"
"What templates do I have in the 'contracts' category?"
"Show me all templates tagged 'hr'"
"Download template T456 so I can edit it locally"
"Deploy version V789 as the active version without deleting the others"
"Schedule this old template for deletion in 30 days"

Depuração

Usando o MCP Inspector

Teste e depure o servidor interativamente:

npx @modelcontextprotocol/inspector npx carbone-mcp

Ou a partir de uma compilação local:

npx @modelcontextprotocol/inspector node dist/index.js

Abra http://localhost:5173 para ver todas as ferramentas, testar chamadas e inspecionar o JSON de solicitação/resposta — sem necessidade de inferência de IA.

Ver Logs do Servidor

# macOS — Claude Desktop logs
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
Get-Content "$env:APPDATA\Claude\logs\mcp*.log" -Wait -Tail 50

Procure por:

✅ Carbone MCP Server v1.x.x started (stdio)
❌ Quaisquer mensagens de erro ou rastreamentos de pilha

Verificação de Saúde (somente modo HTTP)

Ao executar em modo HTTP, o servidor expõe um endpoint de saúde:

curl http://localhost:3000/health

{
  "mcp":    { "version": "1.2.2" },
  "carbone": { "version": "5.x.x" }
}

O campo carbone mostra a conectividade do backend:

{ "version": "..." } — acessível e autenticado
{ "error": "unauthorized", "message": "..." } — acessível, mas sem chave de API ou com chave inválida
{ "error": "unreachable", "message": "..." } — erro de rede, tempo limite ou resposta inesperada

Segurança

⚠️ Entradas de arquivo e URL (SSRF / arquivos locais) As ferramentas aceitam um caminho local, uma URL HTTPS ou base64 para file / template e os parâmetros JSON por referência (data, complement, …). Duas proteções se aplicam:

URLs são resolvidas e recusadas quando apontam para loopback, endereços privados (RFC1918), link-local (incl. metadados de nuvem 169.254.169.254), CGNAT ou endereços reservados — e cada salto de redirecionamento é verificado novamente. Defina CARBONE_ALLOW_PRIVATE_NETWORK=true apenas em uma implantação confiável que precise de hosts de template internos.
Caminhos locais são legíveis somente em stdio, onde o servidor já executa como você. No modo HTTP, eles são recusados, para que um chamador remoto nunca possa fazer o servidor ler seu próprio sistema de arquivos.

⚠️ Compartilhamento de chave de API de nível de servidor (modo HTTP) Se você definir CARBONE_API_KEY em um servidor HTTP e deixar CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false (o padrão), solicitações sem chave Bearer usarão essa chave como fallback — qualquer pessoa que possa acessar a porta pode gastar essa conta Carbone. Defina como true para exigir que cada cliente traga sua própria chave, ou exponha a porta apenas em uma rede confiável. (Não aplicável quando nenhuma chave de servidor está definida, ex.: Carbone on-premise sem autenticação.)

⚠️ Injeção de Prompt Conectar um assistente de IA a qualquer serviço externo traz riscos inerentes. Um documento ou template malicioso pode conter instruções que enganam a IA para executar ações não intencionais (ex.: exfiltrar dados, excluir templates). Sempre revise o que seu cliente de IA está prestes a fazer antes de confirmar chamadas de ferramentas.

⚠️ Proteção da Chave de API

Nunca envie CARBONE_API_KEY para o controle de versão
Use variáveis de ambiente ou um gerenciador de segredos
Rotacione as chaves de API regularmente em account.carbone.io

⚠️ Segurança de Templates

Envie apenas templates de fontes confiáveis
Revise os templates antes de implantá-los
Use o versionamento de templates para facilitar a reversão

⚠️ Privacidade de Dados

A Carbone não armazena seus dados de documentos após a renderização
Use CARBONE_BASE_URL para apontar para uma instância auto-hospedada para máximo controle
Veja a Política de Privacidade para detalhes

Sintaxe de Templates

Projete templates no Word, Excel, LibreOffice ou HTML com tags {d.field}:

Dear {d.customer.name},

Your invoice total is {d.total:formatC(EUR)}.

Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC(EUR)}
{d.items[i+1]}

Guias e melhores práticas:

Carbone Skill — Referência universal de sintaxe de templates Carbone para ferramentas de IA (baixar .skill · GitHub)
Sintaxe de templates
Guia de templates HTML
Guia de templates Markdown

Formatos de Saída Suportados

Categoria	Formatos
Documentos	PDF, DOCX, XLSX, PPTX, ODT, ODS, ODP, ODG, RTF, EPUB
Imagens	PNG, JPG, WEBP, SVG, TIFF, BMP, GIF
Web / Texto	HTML, TXT, CSV, MD, XML

Matriz completa de conversão: carbone.io/documentation

Contribuindo

Aceitamos contribuições:

🐛 Reporte bugs via GitHub Issues
💡 Solicite recursos ou sugira melhorias
📝 Melhore a documentação
🧪 Adicione testes para aumentar a cobertura
🔧 Envie pull requests com correções de bugs ou melhorias

Veja CONTRIBUTING.md para diretrizes.

Desenvolvimento

npm run dev          # Run with tsx (no build needed)
npm run build        # Compile TypeScript → dist/
npm test             # Run the test suite (integration tests run only with CARBONE_TEST_API_KEY)
npm run test:watch   # Watch mode
npm run test:integration  # Real API tests (requires CARBONE_TEST_API_KEY)
npm run test:coverage     # Coverage report

Suporte

🤖 Documentação MCP: carbone.io/documentation/developer/ai/mcp.html
📚 Documentação da API: carbone.io/documentation/developer/http-api/introduction.html
📚 Documentação de Templates: carbone.io/documentation/design/overview/getting-started.html
🐛 Relatórios de Bugs: GitHub Issues
💬 Chat ao Vivo: carbone.io (widget no canto inferior direito)
📧 Empresarial: contact@carbone.io
📋 Especificação OpenAPI: carbone.OpenAPI.yml

Licença

Apache 2.0 — veja LICENSE