Carbone

Carbone MCP サーバー

テンプレートと JSON データから本番環境で使える PDF、Word、Excel、PowerPoint ドキュメントを自動生成し、Claude、Cursor、VS Code、または任意の MCP クライアントから 100 種類以上の形式間でファイルを変換できます。Carbone ドキュメント生成 API の公式サーバーです。

• ファイルを変換： DOCX、XLSX、PPTX、HTML、Markdown、PDF を PDF、画像、CSV、ODT、およびその他の出力形式に変換します。
• JSON でテンプレートに入力： Word、Excel、PowerPoint、LibreOffice、HTML、Markdown で {d.field} タグを使ってテンプレートを作成するか、既存の PDF フォームに入力します。
• PDF を仕上げる： パスワード、透かし、PDF/A、ページ範囲、および変換ツール（LibreOffice、OnlyOffice、Chromium、Carbone ICE）を選択できます。
• バッチ処理とローカライズ： 1 回のリクエストで最大 100 件のドキュメントを処理し、Webhook に送信します。指定した為替レートで翻訳、タイムゾーン、通貨換算を行います。
• テンプレートライブラリを管理： テンプレートをアップロード、バージョン管理、分類、デプロイ、ダウンロードし、テンプレートが必要とするデータを確認できます。

依頼できること

これらは、プランに加入していない場合でも、どの Carbone アカウントでも利用できます（その場合、PDF には透かしが入ります）。

• 「この Markdown を PDF に変換して：# Quarterly update …」
• 「この JSON で請求書テンプレートに入力して、PDF を作成して：{"customer": "Acme", "total": 1500}"
• 「この契約書テンプレートに必要なデータは何ですか？」（inspect_template はタグを一覧表示し、サンプル JSON の下書きを作成します）

Salesforce、HubSpot、Notion、Stripe を使った例など、プロンプトの例もご覧ください。

クイックスタート

1.x からアップグレードする場合は、アップグレードに関する注意事項をご覧ください。HTTP デプロイメントはセキュリティ修正のため、今すぐアップグレードしてください。

前提条件

• Carbone アカウントが必要です。account.carbone.ioで作成してください。ホスト型サーバーでは、このアカウントでサインインします。アカウントがプランに加入すると（Free プランを含む）本番キーが使われ、それまではテストキーが使われます。ローカルパッケージと Docker では、2 種類のキーのいずれかを直接使用します（詳細）：
  • テストキー： 透かし入り PDF を無制限かつ無料で作成できます（PDF 出力のみ）。このキーで保存したテンプレートは最大 30 日間保持されます。
  • 本番キー： あらゆる出力形式に対応し、透かしは入りません。Free プランでは月 100 件のドキュメントを利用できます。
• ローカルパッケージ（npx carbone-mcp）には Node.js 20.3 以降が必要です。node --version で確認してください。Docker イメージでは Docker のみが必要です。

セットアップを選択

セットアップ	実行方法	クライアント	ローカルファイル
ホスト型サーバー（HTTP）	https://mcp.carbone.io。インストール不要	claude.ai、Claude Desktop、Claude Code、VS Code、Cursor、…：Carbone アカウントでサインイン	❌ URL と base64 のみ
ローカルパッケージ（stdio）	マシン上で npx carbone-mcp を実行	Claude Desktop、Claude Code、VS Code、Cursor、およびローカルサーバーを起動できる任意のクライアント	✅ ローカルパスを読み取り、ドキュメントをディスクに保存
Docker（HTTP）	独自のサーバー	Authorization ヘッダーを送信できるクライアント：Claude Code、VS Code、Cursor、…	❌ URL と base64 のみ

claude.ai と Claude Desktop： ホスト型サーバーをコネクターとして追加してください。Claude Desktop でコンピューター上のファイルを読み書きするには、代わりにローカルパッケージを使用してください。

ローカルパッケージ（stdio）

ほとんどのクライアントでは、次の設定を使用します。

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

クライアント	設定する場所
Claude Desktop	Settings → Developer → Edit Config を開くと、claude_desktop_config.json が表示されます（macOS：~/Library/Application Support/Claude/、Windows：%APPDATA%\Claude\）。その後、Claude Desktop を終了して再起動してください。
Cursor	~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1つのプロジェクト）

Claude Code：

claude mcp add --env CARBONE_API_KEY=your_api_key_here --transport stdio carbone -- npx -y carbone-mcp

VS Code： .vscode/mcp.json では mcpServers ではなく servers を使用します。入力変数を使うと、VS Code はキーを一度だけ尋ね、安全に保存します。

{
  "inputs": [
    { "type": "promptString", "id": "carbone-api-key", "description": "Carbone API key", "password": true }
  ],
  "servers": {
    "carbone": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "carbone-mcp"],
      "env": { "CARBONE_API_KEY": "${input:carbone-api-key}" }
    }
  }
}

次に、「Carbone には何ができますか？」 と尋ねてみてください。

クライアントのドキュメント：Claude Desktop · Claude Code · VS Code · Cursor

ホステッドサーバー（mcp.carbone.io）

インストールは不要です。Streamable HTTP 経由で https://mcp.carbone.io に接続し、クライアントがブラウザーで account.carbone.io を開いたら、Carbone アカウントでサインインしてください。HTTP 経由では、ファイル入力は URL または base64 で指定する必要があります（ファイル入力）。

Claude Code： サーバーを追加した後、/mcp を実行し、carbone を選択して Authenticate を選びます。

claude mcp add --transport http carbone https://mcp.carbone.io

VS Code（.vscode/mcp.json）：サーバーの起動時にサインインを求められます。

{
  "servers": {
    "carbone": { "type": "http", "url": "https://mcp.carbone.io" }
  }
}

Cursor（~/.cursor/mcp.json または .cursor/mcp.json）：その後、Cursor の MCP 設定からサインインします。

{
  "mcpServers": {
    "carbone": { "url": "https://mcp.carbone.io" }
  }
}

claude.ai と Claude Desktop のコネクター

1. https://mcp.carbone.io の URL を指定して、カスタムコネクターを追加します。OAuth クライアント ID とシークレットは空欄のままにします。
2. Connect をクリックし、Carbone アカウントでサインインして承認します。

組織で利用する場合、各メンバーは自身の Carbone アカウントで接続し、各自のアカウントに対してドキュメントが計上されます。Claude Desktop でも同じコネクターを使用できます。コンピューター上のファイルを読み込んだり保存したりするには、代わりにローカルパッケージを使用してください。

ファイルの入出力

ファイル入力

file（convert_document）と template（render_document、inspect_template、upload_template）では、次の形式を使用できます。

形式	例	stdio	HTTP
絶対ローカルパス	/Users/me/invoice.docx、~/invoice.docx、C:\Users\me\invoice.docx	✅	❌ 拒否
URL	https://example.com/invoice.docx	✅	✅
Base64	ファイルの内容を base64 でエンコードしたもの	✅	✅

invoice.docx のようなファイル名だけの文字列など、その他の文字列は base64 として読み込まれ、失敗します。相対パス（./…、../…）は、サーバーの作業ディレクトリを基準に解決されます。作業ディレクトリはクライアントが選択するため、絶対パスを使用してください。JSON パラメーター（data、complement、…）でも、JSON ファイルを指すパス、URL、または base64 文字列を指定できます（詳細）。

出力の受け渡し

出力	stdio（ローカルクライアント）	HTTP（リモート／セルフホスト）
テキスト：HTML、TXT、CSV、MD、XML、JSON（テンプレートのサンプル）	インラインテキスト	インラインテキスト
画像：PNG、JPG、GIF、WEBP	インライン画像	インライン画像
その他すべて：PDF、Office、SVG、TIFF…	一時ファイルに保存され、パスが返されます	ダウンロード添付ファイルとして返されます

任意のパスに保存する（outputPath、stdio のみ）、任意の形式で添付ファイルを取得する（asAttachment）、または一度限りのダウンロードリンクを取得する（returnLink）こともできます。出力とファイルの受け渡しを参照してください。

Claude Desktop はインラインのバイナリー添付ファイルを表示できません（画像として誤って処理します）。PDF ファイルと Office ファイルでは、デフォルトの一時ファイルパスを使用するか、returnLink を指定してダウンロード URL を取得してください。

ツール

ツール	機能
convert_document	ファイルを別の形式に変換します。Carbone タグはそのまま保持されます
render_document	JSON データをテンプレートに適用し、結果を変換できます（たとえば PDF に変換できます）
inspect_template	テンプレートのタグを一覧表示し、一致するサンプルデータセットを返します。アカウントでレンダリングを1回実行します（ドキュメント生成1回分としてカウントされます）
list_templates	保存済みテンプレートを、カテゴリ、名前、IDで絞り込んで一覧表示します
list_categories	アカウントのテンプレートカテゴリを一覧表示します
list_tags	テンプレート全体で使用されているタグを一覧表示します
upload_template	再利用可能なテンプレートを、バージョン、カテゴリ、タグとともに保存します
update_template_metadata	テンプレートのバージョンの名前変更、カテゴリ設定、タグ付け、デプロイ、削除予約を行います
delete_template	テンプレートまたはそのバージョンをすぐに削除します
download_template	テンプレートの元ファイル、または一緒に保存されたサンプルデータをダウンロードします
get_api_status	Carbone API の稼働状況とバージョンを確認します
get_capabilities	形式、機能、使用例を要約します

すべてのパラメーターと使用例：docs/API.md。

プロンプトの例

ほかのツールとの併用。 Carbone は、別の MCP サーバーが取得したデータを完成したドキュメントに変換します。これらの例では、そのサーバー（Salesforce、HubSpot、Notion、Stripe など）が同じクライアントに接続されていることを前提としています。

• 「Salesforce から Acme Corp の商談とその製品を取得し、「Sales quote」テンプレートに入力して、PDF を渡してください」
• 「今週、Closed Won に移行した HubSpot の各取引について、「Service agreement」テンプレートに入力し、PDF を ~/Contracts に保存してください」
• 「「Invoice」テンプレートを調べ、フィールドを HubSpot の「Acme renewal」取引に対応付け、レンダリング前に JSON を表示してください」
• 「Notion の「Sprint 42」データベースで Done とマークされたタスクを集め、「Sprint report」テンプレートに DOCX として入力してください」
• 「Acme Corp の先月の支払い済み Stripe 請求書を一覧表示し、「Statement」テンプレートで口座明細を作成してください」
• 「「Workshop」Google Sheet から参加者リストを読み込み、「Certificate」テンプレートで参加者ごとに証明書を作成してください」
• 「今週 GitHub でマージされたプルリクエストを「Release notes」テンプレートにまとめ、Slack の #releases に2行の要約を投稿してください」

テンプレートとデータ

• 「{customer: 'Acme Corp', total: 1500, items: [...]} を使って、テンプレート 1530905183164918624 から請求書を生成してください」
• 「~/hr/jane-doe.json を使って ~/templates/offer-letter.docx に入力し、PDF を ~/Documents/offer-jane-doe.pdf として保存してください」
• 「レイアウトを確認できるように、タグを表示したままテンプレート 1530905183164918624 を PDF で表示してください」

変換

• 「Carbone ICE コンバーターを使って /Users/me/contracts/contract.docx を PDF に変換してください」
• 「https://example.com/sales.xlsx をセミコロン区切りの CSV に変換してください」
• 「この PDF を PNG のサムネイルとしてレンダリングしてください」

一括処理とローカライズ

• 「~/data/invoices.json の顧客ごとに請求書を1つ作成し、ファイル名を invoice-{d.id} とした ZIP でまとめて、Webhook https://example.com/hook に送信してください」
• 「同じテンプレートから、この請求書をフランス語、ドイツ語、スペイン語で生成してください」
• 「価格を 1.08 のレートで EUR から USD に換算し、日付はニューヨーク時間にしてレポートをレンダリングしてください」

PDF オプションとテンプレートライブラリ

• 「この DOCX を、開くためのパスワードを 'secret123' にし、不透明度20%の DRAFT 透かしを入れて PDF に変換してください」
• 「この NDA の1〜5ページを、アーカイブ用に PDF/A-2b のコピーとして作成してください」
• 「請求書テンプレートの最新バージョンをデプロイし、古いバージョンを30日後に削除するよう予約してください」

トラブルシューティング

症状	原因と対処法
ツールエラー Authentication failed: …（キーが設定されていない、または Carbone API に 401 で拒否されるキー）	stdio： クライアント設定の env に CARBONE_API_KEY を設定し、クライアントを再起動してください（設定されていない場合、サーバーは起動時に停止し、CARBONE_API_KEY environment variable is required と表示されます）。セルフホスト型 HTTP： Authorization: Bearer <key> を送信してください。CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true を設定したサーバーでは、すべてのリクエストでこのヘッダーが必要です。account.carbone.io でキーを確認してください。
mcp.carbone.io で再度サインインを求められる、またはサインインに失敗する	再接続してください。Claude では、コネクターを Disconnect してから Connect します。Claude Code では、/mcp → Clear authentication の順に選択し、続けて Authenticate を選択します。
HTTP 403 Invalid Origin: <host>	localhost 以外のホストから提供されているブラウザベースのクライアントです。そのホスト名を MCP_ALLOWED_ORIGINS に追加してください。
ブラウザーでエンドポイントを開くと HTTP 405 Method not allowed が表示される	想定どおりの動作です。エンドポイントが応答するのは MCP の POST リクエストのみです。MCP クライアントで接続し、GET /health でサーバーを確認してください。
HTTP 413 Request body too large が表示される、または stdio 接続が切れる	1 つの MCP メッセージが MCP_MAX_BODY_BYTES を超えています（デフォルトは 60 MB で、stdio メッセージにも適用されます）。大きなファイルはインラインの base64 ではなく URL（stdio ではローカルパスも可）で渡すか、上限を引き上げてください。
Rate limit exceeded. Please wait N second(s)	Carbone API が 429 を返しました。表示された時間だけ待ってから、もう一度お試しください。
{d.name} などのタグが出力に残っている	convert_document は単純な変換処理であり、タグを保持します。データを指定して render_document を使用してください。
すべての PDF にウォーターマークが入る、または PDF しか動作しない	テストキーを使用しています。このキーではウォーターマーク入りの PDF のみが生成されます。mcp.carbone.io では、account.carbone.io でプランを開始してください（Free プランで十分です）。サーバーは自動的に本番キーに切り替わります。ローカルでは本番キーを使用してください。
ファイル名（invoice.docx）を指定すると失敗する	パスのみのファイル名は base64 として読み込まれます。絶対パス（stdio）、URL、または base64 を渡してください（ファイル入力）。
アップロード後も、テンプレート ID でのレンダリングに古いバージョンが使われる	テンプレート ID でのレンダリングには、デプロイ済みのバージョン（最も新しい deployedAt）が使われます。update_template_metadata を使用して新しいバージョンをデプロイするか（templateId = そのバージョンの ID、deployedAt = 42000000000）、バージョン ID でレンダリングしてください。
PDF にパスワード、ウォーターマーク、または PDF/A が適用されない	PDF/A、ページ範囲、アクセシビリティにはデフォルトのコンバーター L（LibreOffice）が使用されます。パスワード、権限、ウォーターマークには O、C、I が適用されます。PDF から PDF への変換では、サーバーが hardRefresh を設定するため、hardRefresh: false を渡さないでください。
Claude Desktop に Carbone ツールが表示されない、またはサーバーが切断される	~/Library/Logs/Claude/（macOS）または %APPDATA%\Claude\logs\（Windows）にある mcp-server-carbone.log（サーバーの stderr）を確認してください。正常に起動すると、ログに Carbone MCP Server v<version> started (stdio) と表示されます。
AI クライアントを使わずにサーバーをテストしたい	MCP Inspector（Node.js 22.19+）を実行してください：npx @modelcontextprotocol/inspector -e CARBONE_API_KEY=your_api_key_here npx carbone-mcp。ツールの一覧と、各リクエストおよびレスポンスを確認できます。

セルフホスティング

Docker

このイメージは、ポート 3000 で Streamable HTTP を提供します。このクイックスタートではサーバーキーを設定しません。各クライアントは Authorization: Bearer <key> で独自のキーを送信します（Carbone アカウントでのサインインは mcp.carbone.io 専用です）。また、このポートにアクセスできるのはお使いのマシンからのみです。

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 carbone/carbone-mcp
curl http://localhost:3000/health

Authorization ヘッダーにキーを指定して、クライアントを接続します。

claude mcp add --transport http carbone http://localhost:3000 --header "Authorization: Bearer your_api_key_here"

VS Code と Cursor では、ホスト型サーバーの設定を使用し、URL を http://localhost:3000 にして、"url" の隣に "headers": { "Authorization": "Bearer your_api_key_here" } を追加します。VS Code では、promptString 型の inputs エントリー（"Bearer ${input:carbone-api-key}"）を使ってキーを入力するよう促すことができます。Cursor では、環境変数から読み込むことができます（"Bearer ${env:CARBONE_API_KEY}"）。ほかのマシンからアクセスできるようにするには、TLS リバースプロキシの背後でポートを公開し、サーバーには CARBONE_API_KEY を設定せず（または CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true を設定し）、ブラウザーベースのクライアントのホスト名を MCP_ALLOWED_ORIGINS に列挙します。

共有キー方式（1 台のマシンで 1 人のユーザーが使う場合）。 サーバーレベルのキーを設定すると、クライアントはキーを送信せずに接続できます。

docker run -d --name carbone-mcp -p 127.0.0.1:3000:3000 -e CARBONE_API_KEY=your_api_key_here carbone/carbone-mcp

使用する前に、共有キーに関する警告をお読みください。

Docker Compose： compose.yml は、このリポジトリからイメージをビルドし、127.0.0.1 のみにバインドして、サーバーキーを設定せず、.env.example にあるすべての変数を引き継ぎます。docker compose up -d で起動します。Compose はシェルまたは .env ファイルから CARBONE_API_KEY も読み込みます。設定されている場合は、共有キー方式が使われます。

Claude Desktop 用にイメージを stdio サーバーとして実行する方法については、Docker Hub ページをご覧ください。

オンプレミスの Carbone

Carbone をオンプレミスで実行している場合は、CARBONE_BASE_URL でサーバーの接続先インスタンスを指定します。API キーは不要です。たとえば、CARBONE_BASE_URL=https://your-carbone-server.com npx carbone-mcp を実行するか、docker run に -e CARBONE_BASE_URL=https://your-carbone-server.com を追加します。

設定

変数	デフォルト	用途
CARBONE_API_KEY	なし	Carbone API キーです。Carbone Cloud の stdio では必須、HTTP では任意です（セキュリティ）
CARBONE_BASE_URL	https://api.carbone.io	Carbone API の URL です。オンプレミスのインスタンスを指定する場合に設定します（キーは不要です）
CARBONE_TIMEOUT	60000	Carbone API リクエストのタイムアウト（ミリ秒）です。Carbone Cloud 自体の上限は 60 秒です
CARBONE_MAX_FILE_BYTES	104857600 (100 MB)	パス、URL、または base64 から読み込む入力ファイルの最大サイズです
MCP_TRANSPORT	stdio（Docker では http）	stdio または http
MCP_PORT	3000	HTTP ポートです
MCP_PATH	/	HTTP エンドポイントのパスです。/health は指定できません
MCP_MAX_BODY_BYTES	62914560 (60 MB)	MCP メッセージの最大サイズです。HTTP ボディの場合はこれを超えると 413 になり、stdio メッセージにも適用されます
MCP_ALLOWED_ORIGINS	なし（localhost は常に許可されます）	HTTP：許可するブラウザーの Origin ホスト名をカンマ区切りで指定します
CARBONE_REQUIRE_CLIENT_AUTH_HEADER	false	HTTP：true にすると、独自の Bearer キーを送信しないリクエストを拒否します
CARBONE_ALLOW_PRIVATE_NETWORK	false	true にすると、URL 入力からプライベートアドレスや内部アドレスにアクセスできます

説明の全文は、docs/API.md の設定をご覧ください。

セキュリティ

• URL 入力とローカルファイル。 プライベートアドレスまたは内部アドレス（localhost、RFC 1918、クラウドメタデータ）に解決される URL は、CARBONE_ALLOW_PRIVATE_NETWORK=true が設定されていない限り拒否されます（詳細）。ローカルパスは、サーバーがユーザー自身として実行される stdio でのみ読み取られます。HTTP 経由では拒否されます。
• 共有サーバーキー（HTTP）。 HTTP サーバーで CARBONE_API_KEY が設定され、CARBONE_REQUIRE_CLIENT_AUTH_HEADER=false（デフォルト）の場合、Bearer キーを含まないリクエストはすべてそのキーを使用します。ポートにアクセスできる人は誰でも、その Carbone アカウントを利用できます。サーバーは起動時に警告を表示します。完全に信頼できるネットワーク以外では、このようなポートを公開しないでください。または、CARBONE_REQUIRE_CLIENT_AUTH_HEADER=true を設定して、各クライアントが独自のキーを提示するようにしてください。サーバーキーが設定されていない場合（認証なしのオンプレミス Carbone など）は適用されません。
• ブラウザーのオリジン（HTTP）。 Origin ヘッダーが存在するものの許可されていないリクエストには 403 が返されるため、悪意のあるウェブページがローカルで実行中のサーバーにアクセスしてキーを使用すること（DNS リバインディング）を防げます。localhost、127.0.0.1、[::1] は許可されます。信頼するブラウザーベースのクライアントは MCP_ALLOWED_ORIGINS に列挙してください。Origin のないリクエスト（デスクトップ、CLI、サーバーサイドのクライアント）には影響しません。
• プロンプトインジェクション。 ドキュメントやテンプレートには、データを別の場所に送信したり、テンプレートを削除したりするなど、AI を意図しない操作に誘導する指示が含まれている場合があります。ツール呼び出しを確定する前に、クライアントが実行しようとしている内容を確認してください。
• API キー。 バージョン管理に含めず、クライアントのシークレット入力または環境変数を通じて渡し、account.carbone.io で定期的に更新してください。
• データ。 Carbone は、アップロードされたテンプレートとサンプルを保存します。また、returnLink またはウェブフックでレンダリングされたドキュメントは、ダウンロードされるまで保持します。プライバシーポリシーをご覧ください。完全に管理するには、Carbone をオンプレミスで実行してください。

テンプレートの作成

Word、Excel、PowerPoint、LibreOffice、HTML、または Markdown でテンプレートを作成し、データを挿入する場所にタグを配置します。

Dear {d.customer.name},
Your invoice total is {d.total:formatC()}.
Items:
{d.items[i].description}  {d.items[i].quantity}x  {d.items[i].price:formatC()}
{d.items[i+1]}

{d.items[i]} … {d.items[i+1]} は、項目ごとに行を繰り返します。基本から始めるか、AI ツール向けのテンプレート構文リファレンスである Carbone Skill を AI アシスタントに渡してください（.skill をダウンロード · GitHub）。

コントリビュート

バグ報告、修正、ドキュメントの改善を歓迎します。CONTRIBUTING.md では、開発環境のセットアップ、テスト、デバッグ、プルリクエストの手順について説明しています。

サポート

• ドキュメント： MCP サーバー · HTTP API · テンプレート設計 · OpenAPI 仕様
• バグと機能リクエスト： GitHub Issues
• 質問： carbone.io のライブチャット（右下のウィジェット） · エンタープライズ： [email protected]

ライセンス

Apache 2.0。LICENSE を参照してください。