sheetrender-mcp

@sheetrender/mcp

SheetRender の MCP サーバーです。スプレッドシートの各行から、証明書、手紙、寄付金の領収書、オファーレターなどの PDF を 1 つずつ作成します。

アカウントもインストールも不要で、すぐに始められます。https://mcp.sheetrender.com/mcp を、ChatGPT、Claude、または Streamable HTTP URL に対応したクライアントのコネクターとして追加し、行を貼り付けるか説明してください。SheetRender の組み込みテンプレートにデータが入力され、プレビューと各行の PDF が返されます（詳細）。

SheetRender API キーを使うと、下記の npm パッケージ、または同じホスト URL 経由で、独自の保存済みテンプレート、HTML テンプレート、データセット、バッチジョブなど、すべてのツールを利用できます。

セットアップ

sheetrender.com の「設定」→「API キー」から API キーを取得し、MCP クライアントの設定に以下を追加してください。

{
  "mcpServers": {
    "sheetrender": {
      "command": "npx",
      "args": ["-y", "@sheetrender/mcp"],
      "env": { "SHEETRENDER_API_KEY": "sr_live_..." }
    }
  }
}

SHEETRENDER_API_URL も読み込まれ、デフォルトは https://sheetrender.com です。セルフホストまたはステージング環境を指定する場合にのみ設定してください。

ホスト型エンドポイント

同じサーバーが Streamable HTTP 経由で https://mcp.sheetrender.com/mcp でも実行されるため、ローカルプロセスを起動できないクライアントからも利用できます。インストールは不要です。各リクエストに API キーを含めます。

Authorization: Bearer sr_live_...

このヘッダーを含まないリクエストには、以下で説明する、より小規模なキー不要のツールセットが適用されます。キーはそのリクエストに限り SheetRender API に直接渡され、保存されることはありません。サーバーはセッションを保持しないため、各リクエストは独立しています。

キーの渡し方はクライアントによって異なります。

• Claude Code： claude mcp add --transport http sheetrender https://mcp.sheetrender.com/mcp --header "Authorization: Bearer sr_live_..."

• Cursor、Windsurf、VS Code などの mcp.json を使うクライアント：

  {
    "mcpServers": {
      "sheetrender": {
        "url": "https://mcp.sheetrender.com/mcp",
        "headers": { "Authorization": "Bearer sr_live_..." }
      }
    }
  }
  

• Claude API（Messages API の MCP コネクター）：mcp_servers に {"type": "url", "url": "https://mcp.sheetrender.com/mcp", "name": "sheetrender", "authorization_token": "sr_live_..."} を追加します。

• claude.ai、Claude Desktop、ChatGPT のカスタムコネクターでは、サーバー URL と OAuth クライアントが必要で、静的ヘッダーは使えません。エンドポイントが OAuth に対応するまでは、そこで上記の stdio パッケージを使用してください。ツールは同じで、キーは env に設定します。または、npx mcp-remote https://mcp.sheetrender.com/mcp --header "Authorization: Bearer sr_live_..." をコマンドとして使って中継できます。

プロセスがユーザーのマシン上で動作しないため、stdio サーバーとは次の 2 点が異なります。レンダリングされた PDF は、一時ファイルのパスではなく、インラインの base64 リソースとして返されます（最大 8 MB。これを超えるものはサイズが報告され、ウェブアプリで処理します）。また、読み込むローカルファイルがないため upload_dataset は提供されません。代わりに create_dataset で行を送信してください。

GET /healthz は認証情報なしで 200 を返します。リクエスト本文の上限は 25 MB で、それを超えると 413 が返されます。

sr_ で始まるキーであるだけでは有効性を証明できないため、サーバーは SheetRender API がキーを受け入れるまで待機します。そのキーを使った呼び出しが成功するまでは（通常は list_templates などの最初のツール呼び出し）、リクエストには以下で説明するキーなしの場合と同じ制限が適用されます。本文は最大 2 MB、1 バッチあたり最大 4 件の JSON-RPC メッセージで、すべてのメッセージがネットワークごとの予算に算入されます。API がキーを受け入れると、サーバーはキーそのものではなく、そのハッシュを、最後に成功した呼び出しから 1 時間記憶します。その間、リクエストの本文上限は 25 MB、バッチ上限は 20 件になります。MCP クライアントはリクエストごとに 1 件のメッセージを送信するため、バッチ上限が関係するのは手書きのクライアントのみです。最初の呼び出しで 2 MB を超える本文（大きな create_dataset など）を送信すると、先に小さな呼び出しを行ってから再試行するよう案内する 413 が返されます。キーの有無にかかわらず、すべてのリクエストがサーバー全体の同時処理上限に算入されます。

受け入れ済みのキーでは、1 回のツール呼び出しの引数に最大 600,000 個の値（配列要素とオブジェクトフィールドの合計）を含められます。これは create_dataset の 500,000 セルを扱える量です。まだ受け入れられていないキーでは 20,000 個までです。匿名の呼び出しには、実際の最大呼び出しを少し上回る上限が適用されます。

2 MB を超える本文は、サーバー全体で設けられた少数の大容量本文用スロットのいずれかを使用します。デフォルトは 1 です（LARGE_BODY_MAX_IN_FLIGHT）。Content-Length がそのような本文を示す場合は読み込み前に、ストリーミング中の本文が 2 MB を超えた場合はその時点で、スロットが確保され、応答が終了するまで保持されます。すべてのスロットが使用中の場合、リクエストには Retry-After: 5 を伴う 503 が返され、残りの本文は読み込まれません。25 MB の本文 1 つでも、デコード、解析、転送中に約 100 MB のヒープを使用することがあるため、この値を引き上げるのはヒープ容量に余裕がある場合に限ってください（ホスト型コンテナーのヒープは 192 MB です）。

キーなしの場合（ChatGPT と Claude のディレクトリー一覧）

サーバーで SHEETRENDER_DEMO_API_KEY が設定されている場合、Authorization ヘッダーを送信しないリクエストには、401 ではなく、異なる小規模なツールセットが提供されます。これらのツールは、専用のレンダリングアカウントを通じて、チャット内の行から SheetRender の組み込みテンプレート（修了証明書、手紙、寄付金受領書、採用通知書）にデータを入力します。

• list_document_templates：テンプレートと、そのフィールド（キー、ラベル、必須かどうか、例、文字数および行数の上限）。
• render_documents：1 回の呼び出しにつき最大 25 行で、各行に 1 つの PDF を生成します。ドキュメントごとに PNG プレビューと PDF リンク（どちらも 1 時間後に期限切れ）、必須フィールドが未入力だった行、およびユーザーあたり（Claude では会話あたり）の月間 50 ドキュメントの残数を返します。他のユーザーと共有する上限によって呼び出しが打ち切られた、または拒否された場合は、残数の代わりに上限が共有されていることを示します。呼び出しが拒否または打ち切られた場合は、継続リンクを使ってウェブサイトに行データを引き継げることも示します。フィールドの文字数または行数の上限を超える値は、API の呼び出し前に拒否されます。また、行の拒否について API が返した理由（行番号、フィールド、ルール。値は含みません）も伝えます。
• create_continue_link：最大 100 行を 7 日間保存し、行データを読み込んだ状態でテンプレートのウェブサイト上のページを開くリンクを返します。ユーザーがそこでの続行を希望する場合にのみ呼び出されます。

render_documents には、MCP Apps ビュー ui://sheetrender/documents.html（text/html;profile=mcp-app）が付属しています。プレビューと PDF リンクを並べて表示し、「この行データを使って SheetRender で続行」ボタンを備えています。そのスクリプト src/widget/documents.ts は、deno task build の実行時に esbuild によって dist/widget/documents.js にバンドルされ、リソースの読み込み時にページへインライン化されます。

呼び出し回数はユーザーごとに集計されます。ChatGPT の匿名化された openai/subject がある場合はそれを使い、それ以外の場合はクライアント IP を使います。呼び出し元は誰でも openai/subject を送信できるため、OpenAI が公開している送信元範囲（chatgpt-connectors.json、OPENAI_EGRESS_CIDRS で上書き可能）からのものだけを信頼します。それ以外の場所からの呼び出しは IP で集計されます。ホストされたサーバーは、起動時および 24 時間ごとにこのリストを取得します。取得に失敗した場合、または不正な形式や空の内容が返された場合は、組み込みのコピー（その後は最後に正常に取得できたもの）を保持します。更新ごとに 1 行のログを記録します。また、リスト外から openai/subject を送信した呼び出し数も、最大 1 時間に 1 回ログに記録するため、リストが古くなっていることを検出できます。

サーバーは、サブジェクトまたは IP ごとに 1 時間あたり 30 回までのレンダリングまたは続行呼び出しを許可します（ANON_CALLS_PER_HOUR）。IP で集計される呼び出し元には、IPv4 の /24 または IPv6 の /48 ごとに 1 時間あたり 300 回の第 2 の共有枠も適用されるため、安価なアドレス群も 1 つの呼び出し元として集計されます（ANON_NETWORK_CALLS_PER_HOUR）。Claude の 160.79.104.0/21 ネットワーク（Anthropic が公開している送信範囲であり、Claude API の MCP コネクタも使用）からのすべてのトラフィックは、1 時間あたり 3,000 回の別枠を共有します（CLAUDE_CALLS_PER_HOUR）。Mcp-Session-Id を送信する Claude の各会話には、この枠内でサブジェクトごとに 30 回の枠も適用されます。User-Agent のテキストも _meta も、これらの枠を申告したり、枠から外れたりするためには使えません。 SheetRender API は引き続き、ハッシュ化されたサブジェクトまたは IP に対して月間ドキュメント数を適用します。サブジェクトと IP は SHA-256 ハッシュとしてのみ API に送信されます。リクエストログにはフィンガープリント、検出されたクライアント（chatgpt、claude、または other）、行数が記録されますが、行データは記録されません。

匿名 HTTP リクエスト本文の上限は 2 MB です。これは、すべてのフィールドで上限いっぱいの値を使った 25 行を収められるサイズです。続行リンクの行データの上限は 256 KB です。プライベートソケットのピアはプロキシとして扱い、X-Forwarded-For 内の最後の有効な IP のみを信頼します。デプロイ時の Compose トポロジーと同様に、このリスナーは Caddy の背後に置き、コンテナのポートを外部に公開しないでください。 匿名リクエストにはさらに3つの上限があり、小さなリクエストによってサーバーが大量の出力を生成することはありません。JSON-RPC バッチに含められるメッセージは最大4件です（MCP はプロトコルバージョン 2025-06-18 でバッチ処理を廃止しており、ChatGPT と Claude はリクエストごとに1件のメッセージを送信します）。上限を超えるバッチは、その中の処理が何も実行される前に400で拒否されます。ツール呼び出し以外のメッセージ（initialize、tools/list、resources/read など）は、IPv4 の /24 または IPv6 の /48 ごとに1時間あたり600件までです（ANON_RPC_PER_HOUR）。OpenAI と Claude の送信元 IP 範囲からのトラフィックは、各 IP アドレスが多数のユーザーによって共有されているため、この上限の対象外です。また、API キーの有無にかかわらず、同時に応答できるリクエストは最大64件です（ANON_MAX_IN_FLIGHT）。これらの範囲外では、ネットワークごとに8件までです（ANON_NETWORK_MAX_IN_FLIGHT）。いずれかの上限を超えると、Retry-After: 5 を付けて503または429を返します。SheetRender API がまだ受け付けていない API キーを使ったリクエストには、これら3つすべての上限が適用され、ツール呼び出しも600件のカウントに含まれます。キーが受け付けられると、そのリクエストは全体の同時実行数の上限のみが適用され、バッチには20件のメッセージを含められます。

SheetRender のベアラーキーを含むリクエストでは、上記の API キー用ツールが使われます。不正な形式の Authorization ヘッダーは拒否されます。stdio サーバーでは匿名ツールは提供されません。

自分で実行する

sheetrender-mcp-http は、このパッケージの2つ目のバイナリです。PORT（デフォルトは8080）、HOST（デフォルトは0.0.0.0）、SHEETRENDER_API_URL、MAX_BODY_BYTES、IDLE_TIMEOUT_MS（デフォルトは60000）を読み込み、リクエストごとに1行の JSON を stdout に記録します。ログには、メソッド、パス、ステータス、処理時間、JSON-RPC メソッドとツール名、キーのフィンガープリント（キー自体は記録されません）、および API がそのキーをすでに受け付けているかどうかを示す key_verified が含まれます。

匿名ツールと上記のリクエスト上限（デモキーが設定されていない場合は、キー付きリクエストにも適用されます）については、次の環境変数も読み込みます。

変数
SHEETRENDER_DEMO_API_KEY	専用レンダリングアカウントの sr_ キーです。未設定の場合、匿名ツールは使えず、キーなしのリクエストには401が返されます。
MCP_PUBLIC_URL	ユーザーが貼り付ける URL です。例：https://mcp.sheetrender.com/mcp。バイト単位で完全に一致する必要があります。ビューのサンドボックスオリジンを設定します（Claude はこの正確な文字列をハッシュ化します）。
OPENAI_APPS_CHALLENGE	OpenAI のドメイン検証トークンです。GET /.well-known/openai-apps-challenge でプレーンテキストとして提供されます（未設定の場合は404）。
ANON_CALLS_PER_HOUR	サブジェクトまたは IP ごとの1時間あたりのレンダリング呼び出しと続行呼び出しの上限です。デフォルトは30です。
ANON_NETWORK_CALLS_PER_HOUR	IP でカウントされる呼び出し元について、IPv4 の /24 または IPv6 の /48 ごとの1時間あたりのレンダリング呼び出しと続行呼び出しの上限です。デフォルトは300です。
CLAUDE_CALLS_PER_HOUR	160.79.104.0/21 からのすべてのトラフィックに対する、共有の1時間あたりのレンダリング呼び出しと続行呼び出しの上限です。デフォルトは3000です。
ANON_RPC_PER_HOUR	ツール呼び出し以外の匿名メッセージと、API がまだ受け付けていないキーを使って送信されたすべてのメッセージについて、OpenAI と Claude の範囲外における IPv4 の /24 または IPv6 の /48 ごとの1時間あたりの上限です。デフォルトは600です。
ANON_MAX_IN_FLIGHT	呼び出し元全体で、同時に応答するリクエスト数の上限です（キーの有無は問いません）。デフォルトは64です。
ANON_NETWORK_MAX_IN_FLIGHT	匿名リクエストと、API がまだ受け付けていないキーを使ったリクエストについて、OpenAI と Claude の範囲外における IPv4 の /24 または IPv6 の /48 ごとに同時に応答するリクエスト数の上限です。デフォルトは8です。
LARGE_BODY_MAX_IN_FLIGHT	本文が2 MBを超えるリクエストについて、サーバー全体で同時に処理する数の上限です。デフォルトは1です。このような本文を送信できるのは、API が受け付けたキーのみです。
OPENAI_EGRESS_CIDRS	openai/subject が信頼できると見なされる CIDR を、カンマまたはスペース区切りで指定します。ビルトインの設定と chatgpt-connectors.json のライブ取得の両方を置き換えます。none を指定すると、どのサブジェクトも信頼しません。

SHEETRENDER_DEMO_API_KEY が設定されている場合、ビューのバンドル（dist/widget/documents.js）がないとサーバーは起動を拒否します。このリポジトリの Dockerfile は、非 root のランタイムイメージをビルドします。

docker build -t sheetrender-mcp .
docker run --rm -p 8080:8080 sheetrender-mcp

ツール

• design_template：dataset_id、インラインの rows、data_base64 と data_filename の組み合わせ、または stdio 専用の data_path のいずれか1つだけを使い、さらに例、概要、またはスタイルを指定してデザインします。データファイルは CSV または XLSX 形式で、最大 10 MB です。最大3分間待機し、ステータス、テンプレートの詳細、認証済みプレビュー URL を返します。例には example_base64 と example_filename の組み合わせ、または stdio 専用の example_path を使用します。
• get_design：design_id のステータス、テンプレート ID、名前、列のマッピング、プレビュー URL を取得します。

render_pdf

指定した HTML から1つの PDF をレンダリングします。

引数	型
html	文字列	必須。完全な HTML ドキュメントです。CSS は <style> タグ内にインラインで記述する必要があります。外部スタイルシート、フォント、スクリプトは取得されません。
data	オブジェクト	任意。キーが Jinja 変数になります。たとえば、{"total": "42.00"} を指定すると、HTML で {{ total }} を使用できます。
page_settings	オブジェクト	任意。以下を参照してください。

保存した PDF のパスとサイズを返します。512 KB 未満の場合は、base64 リソースとしてインラインで添付されるため、添付ファイルを表示できるクライアントではドキュメント自体が表示されます。

HTML が 2 MB を超えると拒否されます。このサイズは送信時と、data の置換後のドキュメントの両方で測定されるため、長いデータセットを展開するテンプレートでは、作成したマークアップが上限未満でも上限を超えることがあります。レンダリングアカウントの設定で必要な場合は、「Made with SheetRender」フッターが追加されます。これは render_pdf と render_template の両方に適用されます。

list_templates

引数はありません。保存済みの各テンプレートについて、名前、ID、最終更新日を返します。ユーザーが指定したテンプレート名を、他のツールで必要な ID に変換するために呼び出します。

render_template

アカウントに保存済みのテンプレートから1つの PDF をレンダリングします。

引数	型
template_id	文字列	必須。list_templates から取得します。
data	オブジェクト	必須。1行分の値を Jinja 変数として指定します。
page_settings	オブジェクト	任意。省略すると、テンプレートに保存されたページ設定が維持されます。指定すると、このレンダリングに限り設定が上書きされます。

戻り値は render_pdf と同じです。

create_dataset

JSON の行を、バッチジョブでレンダリングできるデータセットに変換します。通常はこれを使ってバッチを開始します。行を組み立てて送信すると、dataset_id が返されます。

引数	型
template_id	文字列	必須。list_templates から取得します。データセットはそのテンプレートのプロジェクトに作成されます。
rows	オブジェクトの配列	必須。ドキュメントごとにフラットなオブジェクトを1つ指定します。
name	文字列	任意のラベル。保存時のファイル名として使用されます。

ヘッダーは、すべての行のキーを最初に出現した順に統合したものです。そのため、各行のキーが一致している必要はありません。キーがない場合は、行の位置がずれるのではなく、空のセルになります。値はスカラーである必要があります。使用できるのは文字列、数値、真偽値、null です。ネストされたオブジェクトと配列は拒否されます。また、NaN、Infinity、2^53 を超える整数も拒否されます（正確さを保つには文字列として送信してください）。1回の呼び出しにつき、最大 50,000 行、500,000 セルです。

データセット ID、行数、各列の サニタイズ済みキー を返します。このキーはテンプレートのプレースホルダー、filename_template、group_by で参照するもので、ヘッダーと完全には一致しないことがよくあります。たとえば、Invoice No は invoice_no になります。推測せず、この結果からキーを確認してください。

データセットの作成ではドキュメントの利用枠は消費されません。消費されるのはレンダリング時のみです。

upload_dataset

既存のファイルから同じ処理を行います。

引数	型
template_id	文字列	必須。list_templates から取得します。
file_path	文字列	必須。このサーバーを実行しているマシン（SheetRender ではなくユーザーのマシン）上の .csv または .xlsx ファイルです。~ は展開されます。

先頭行はヘッダーである必要があります。20 MB を超えるファイル、拡張子が正しくないファイル、空のファイルは、アップロード前にローカルで拒否されます。戻り値は create_dataset と同じです。

list_datasets

template_idを受け取り、そのテンプレートのプロジェクトにあるすべてのデータセットを新しい順に一覧表示します。ID、行数、列キーも含まれます。ユーザーがすでに読み込んだデータを探したり、filename_templateを書く前やgroup_byを選ぶ前にデータセットの列キーを確認したりするために使います。

create_batch_job

データセットの各行につき1つのPDFをレンダリングするバックグラウンドジョブをキューに追加します。ここから一連の処理を実行します — list_templates → create_datasetまたはupload_dataset → create_batch_job → get_job → get_document。

引数	型
template_id	string	必須です。list_templatesから取得します。
dataset_id	string	必須です。create_dataset、upload_dataset、またはlist_datasetsから取得します。テンプレートと同じプロジェクトに属している必要があります。
filename_template	string	任意です。出力ファイル名のパターンです。例：invoice-{{ invoice_no }}。
group_by	string	任意です。行をグループ化する列キーを指定します。値ごとに複数ページのPDFが1つ作成されます。

get_jobでポーリングするためのジョブIDを返します。知っておくと便利な点として、filename_templateとgroup_byはそれぞれテンプレートとプロジェクトに保存されるため、後続の実行時のデフォルトも変更されます。

サーバーが公開バッチエンドポイントより古い場合、このツールは分かりにくいエラーを返すのではなく、バッチジョブを利用できないことを報告します。3つのデータセットツールも、データセットエンドポイントより古いサーバーに対して同様に動作します。

get_job

job_idを受け取ります。ステータス、処理済みおよび失敗した行数、レンダリングされた各ドキュメントのIDとファイル名を返します。ジョブがqueued、retry_queued、runningの間、ドキュメント一覧は空のままで、ジョブがsucceeded、partial、failed、cancelledに達すると一覧が表示されます。これらのドキュメントIDをget_documentに渡します。

get_document

document_idを受け取り、レンダリングされたPDFを1つダウンロードします。IDは完了したバッチのget_jobから取得します。これ以外にIDを取得する方法はありません。返される内容はrender_pdfと同じで、パス、サイズ、512 KB未満の場合はインラインのblobが含まれます。

バッチ全体が必要な場合は、各ドキュメントを個別に取得するより、ウェブアプリでPDFを結合するかZIPをダウンロードするほうが便利です。

page_settings

どちらのレンダリングツールでも使えます。すべてのフィールドは任意です。

{
  "page_size": "a4",
  "orientation": "portrait",
  "margins": { "top": 15, "right": 15, "bottom": 15, "left": 15 }
}

page_sizeは小文字で指定します：a3、a4、a5、letter、legal、tabloid。余白にはCSSの長さではなく、ミリメートル単位の数値を指定します。

レンダリングされたPDFはシステムの一時ディレクトリに書き込まれます。無効なキー、テンプレートが見つからない場合、レート制限などのAPIエラーは、サーバー独自のメッセージを含むツールエラーとして返されます。

公開APIでは、APIキーごとに1分あたり120件のリクエストが許可されています。上限を超えると429が返され、レート制限中のため、しばらくしてから再試行するようツールが報告します。バッチジョブの作成には別の、より厳しい制限が適用されます。

開発

ホストにnodeやnpmをインストールする必要はありません。scripts/dev.sh installを実行してから、scripts/dev.sh deno task buildとscripts/dev.sh deno task testを実行してください。scripts/dev.sh node dist/http.jsを実行すると、ホストネットワーク上でHTTPサーバーが起動します。

MITライセンスです。