ZapSign (unofficial)

zapsign-mcp

ZapSign API 用の MCP サーバーです。署名者の個人データを渡すことなく、AI エージェントと連携できるように構築されています。

• 48 個のツール：ZapSign の公開 Postman コレクションに含まれるすべてのリクエストに加え、ドキュメントで追加されているもの（ドキュメント、署名者、テンプレート、Webhook、ユーザー、プラン、バックグラウンドチェック、パートナーアカウント）。
• 読み取りはいつでも実行でき、書き込みのたびに確認を求めます。 変更を行うツールには Claude Code の anthropic/requiresUserInteraction マークが付いているため、どの権限モードでも、Claude Code は呼び出しのたびに確認を求めます。ほかのクライアントには読み取り機能のみが提供されます。
• 本番環境は読み取り専用です。 prod サーバーには書き込みツールが一切ありません。sandbox ではすべてのツールを利用できます。
• モデルに渡されるのは、各回答をフィルタリングしたコピーです。 氏名、メールアドレス、書類番号、州、日付は渡されますが、CPF、CNPJ、RFC、CURP、生年月日、写真、署名リンク、IP アドレス、位置情報、電話番号のフィールド、フォームの回答、バックグラウンドチェックの所見は非表示になります。
• 回答全体はローカルログに保存されます。 エージェントにはエントリーの ID のみが渡され、ログの保存場所は伝わりません。
• 依存関係はありません。 1 つの Node ファイルが stdio 経由で MCP と通信するため、ビルドもインストールも不要です。

このプロジェクトは ZapSign とは提携していません。ZapSign は独自の MCP サーバーを ZapSign/api-mcp で公開しています。

要件

• Node.js 22 以降。
• 使用する各環境（sandbox、production、またはその両方）の ZapSign API トークン（ZapSign：Settings → Integration → ZapSign API）。

インストール

次のいずれかを選んでください。

• npm からインストール（推奨）。手動でダウンロードするものはありません。Claude Code は npx -y [email protected] <environment> でサーバーを起動し、初回に指定されたバージョンを取得して、以降はそれを再利用します。バージョンを固定しているため、新しいリリースが実行されるのは番号を変更したときだけです。npm の 1.0.1 以降の各バージョンは GitHub Actions によりこのリポジトリからビルドされ、メンテナーが 2FA で承認した後にのみ公開されます。

• ソースからインストール。リポジトリをクローンし、Node でサーバーを起動します。git pull で更新してください。

  git clone https://github.com/BlancasJ/zapsign-mcp.git ~/zapsign-mcp
  

  その後、以下のコマンドでは npx -y [email protected] sandbox の代わりに node ~/zapsign-mcp/bin/zapsign-mcp.js sandbox を使用してください。

セットアップ

1. トークンを設定する

各環境はそれぞれ固有の変数 ZAPSIGN_SANDBOX_TOKEN または ZAPSIGN_PROD_TOKEN を読み込み、もう一方の変数を読み込むことはありません。トークンはサーバーの起動時ではなく、ツールの呼び出し時に読み込まれます。

macOS では、設定ファイルではなく Keychain にトークンを保存できます。変数が設定されていない場合、サーバーはそこからトークンを読み込みます。

security add-generic-password -s zapsign-mcp-sandbox -a "$USER" -w   # asks for the sandbox token
security add-generic-password -s zapsign-mcp-prod -a "$USER" -w      # asks for the production token

2. Claude Code に追加する

環境ごとに 1 つのサーバーを追加し、zapsign-sandbox と zapsign-prod という名前を付けます（以下の権限ルールではこれらの名前を使用します）。

# With the token in the Keychain (macOS)
claude mcp add --scope user zapsign-sandbox -- npx -y [email protected] sandbox
claude mcp add --scope user zapsign-prod -- npx -y [email protected] prod

# With the token in a variable (any system). Claude Code keeps it in ~/.claude.json.
claude mcp add --scope user zapsign-sandbox -e ZAPSIGN_SANDBOX_TOKEN=your-token -- npx -y [email protected] sandbox

書き込みは、Claude Code が認識するマークを通じて確認を求めます（MCP のドキュメント「Require approval for a specific tool」を参照）。確認を求めない dontAsk モードでは、書き込みは拒否されます。

3. 権限ルールとサンドボックスを追加する

examples/claude-settings.json を ~/.claude/settings.json にマージします。

• permissions.allow：読み取り操作（get_*、list_*）は確認なしで実行されます。
• permissions.ask：何かを変更する各動詞（create_*、add_*、update_*、delete_* など）では確認を求めます。 ツールに付いているマークによって Claude Code はすでに確認を求めますが、これらのルールは二重の保護層になります。
• permissions.deny：エージェントのファイルツールはログフォルダーを読み取れず、WebFetch は ZapSign の API にアクセスできません。
• sandbox：Claude Code の Bash サンドボックスを有効にします。シェルコマンドも、シェルから起動するプログラム（Python や Node のスクリプトを含む）も、ログフォルダーを読み取ったり、手元にトークンがあっても ZapSign の API にアクセスしたりできません。autoAllowBashIfSandboxed: false を設定すると、これまでどおりコマンドの実行前に Claude Code が確認を求めます。この設定がない場合、サンドボックスを有効にすると、サンドボックス内のすべてのコマンドが確認なしで実行されます。

deny ルールと sandbox ブロックは必ず残してください。これらがないと、エージェントはフィルターされていない回答を開いたり、このサーバーを介さずに ZapSign を呼び出したりできてしまいます。XDG_STATE_HOME を設定している場合は、両方のログパスを $XDG_STATE_HOME/zapsign-mcp に変更してください。

サンドボックスは、ほかのすべてのコマンドでできることも制限します。デフォルトでは、作業フォルダーと一時フォルダーにのみ書き込み、これまでアクセスしたことのないホストへの接続は、セッションごとに一度確認を求めます。sandbox.filesystem.allowWrite と sandbox.network.allowedDomains で制限を緩和できます。ただし、deniedDomains の設定は引き続き優先されます。

ツール

読み取り（自由に実行できます）：

ツール	リクエスト
get_document	GET /api/v1/docs/{doc_token}/
list_documents	GET /api/v1/docs/
get_document_audit_trail	GET /api/v1/docs/signer-log/{doc_token}
get_signer	GET /api/v1/signers/{signer_token}/
get_signer_validations	GET /api/v1/signer-verification-details/{signer_token}/
list_templates	GET /api/v1/templates/
get_template	GET /api/v1/templates/{template_token}/
get_plan	GET /api/v1/info-plan/
list_users	GET /api/v1/users/
get_partner_plans_csv	GET /api/v1/info-plan/partners-csv/
get_background_check	GET /api/v1/checks/{check_id}/
get_background_check_details	GET /api/v1/checks/{check_id}/details/

書き込み（サンドボックスのみ。各呼び出しの前に確認します）：

ツール	リクエスト
create_document	POST /api/v1/docs/
create_document_async	POST /api/v1/docs/async/
create_document_from_template	POST /api/v1/models/create-doc/
create_document_from_template_async	POST /api/v1/models/create-doc/async/
add_extra_document	POST /api/v1/docs/{doc_token}/upload-extra-doc/
add_extra_document_from_template	POST /api/v1/models/{doc_token}/upload-extra-doc/
place_signatures	POST /api/v1/docs/{doc_token}/place-signatures/
reorder_envelope_documents	PUT /api/v1/docs/{doc_token}/document-display-order/
resend_notifications	POST /api/v1/docs/{doc_token}/resend-notifications-bulk/
update_document	PUT /api/v1/docs/{doc_token}/
reprocess_document	POST /api/v1/docs/{doc_token}/reprocess-doc/
delete_document	DELETE /api/v1/docs/{doc_token}/
delete_signer_groups	DELETE /api/v1/signature-group/{doc_token}/
reject_document	POST /api/v1/refuse/
reject_document_by_user	POST /api/v1/refuse/by-user/
validate_pdf_signature	POST /api/v1/validate-pdf-signature/ （ローカルの PDF をアップロードします）
sign_in_batch	POST /api/v1/sign/
add_timestamp	POST /api/v1/timestamp/
add_timestamp_keeping_signature	POST /api/v1/timestamp/no-signature
add_signer	POST /api/v1/docs/{doc_token}/add-signer/
update_signer	POST /api/v1/signers/{signer_token}/
delete_signer	DELETE /api/v1/signer/{signer_token}/remove/
reset_signer_validation_attempts	PUT /api/v1/reset-auth-attempts/{signer_token}/
create_template	POST /api/v1/templates/create
update_template	PUT /api/v1/templates/{template_token}/
update_template_form	POST /api/v1/templates/update-form/
delete_template	DELETE /api/v1/templates/{template_token}/
create_webhook	POST /api/v1/user/company/webhook/
delete_webhook	DELETE /api/v1/user/company/webhook/delete/
create_webhook_header	POST /api/v1/user/company/webhook/header/
delete_webhook_header	DELETE /api/v1/user/company/webhook/header/delete/
create_user	POST /api/v1/users/create-user
delete_user	DELETE /api/v1/users/{user_email}/
create_background_check	POST /api/v1/checks/
create_partner_account	POST /api/v1/partner/company/
update_partner_payment_status	POST /api/v1/partner/update-payment-status/

書き込みでは、リクエストの JSON を body として受け取り、そのまま ZapSign に送信するため、 ZapSign のドキュメントにあるすべてのオプションを利用できます。パスに含まれるトークンとメールアドレスは事前に検証されるため、リクエストの送信先を別の場所に変更することはできません。

モデルに表示される内容

lib/response-filter.jsで決まります。表示可能なキーが一覧になっており、それ以外のキーは名前をそのまま残して値が[hidden]になります。そのため、ZapSignが後から追加したフィールドは、誰かが一覧に追加するまで非表示です。

• 表示：トークン、状態、イベントの日付、設定、件数、名前、メールアドレス、本人確認書類の番号。
• 非表示：CPF、CNPJ、RFC、CURPなどのID（句読点の有無にかかわらず、テキスト内に記載されている場合も対象）、生年月日、写真と署名画像、署名リンクとファイルリンク（ホストのみ表示）、IPアドレスと位置情報、電話番号フィールド（末尾4桁のみ表示）、フォームの回答、バックグラウンドチェックの結果、Webhookのヘッダー値。
• エラーにも同じフィルターが適用されます。

既知の抜けがあります。署名者のトークンは表示され、署名リンクの生成に十分な情報です。自由記述のテキスト内に書かれた電話番号、座標、生年月日はマスキングされません。

ログ

すべての呼び出しが引数とZapSignの完全な応答を含む状態で、$XDG_STATE_HOME/zapsign-mcp/（デフォルトは~/.local/state/zapsign-mcp/）のsandbox/とprod/に完全な形で保存されます。

• 呼び出しごとに1行のJSON形式で、1日ごとに1ファイルが作成され、30日間保持されます。
• フォルダーは0700、ファイルは0600です。
• webhooks.jsonlには作成されたすべてのWebhookのIDが保存され、削除されることはありません。ZapSignにはWebhookを一覧表示するリクエストがなく、IDはWebhookを削除する唯一の方法だからです。

エージェントに返される応答にはログエントリのIDが記載され、フォルダーは記載されません。Readの拒否ルールにより、Claude Codeのファイルツールと、BashでClaude Codeが認識するファイルコマンド（cat、head、tail）はログにアクセスできません。サンドボックスのdenyReadにより、シェルコマンドが起動するすべてのプログラムからもログにアクセスできません。

制限事項

フィルターと本番環境の読み取り専用サーバーによる制限は、エージェントがこのサーバーを経由する場合にのみ有効です。設定例を使うと、シェルコマンドはログを読み取れず、ZapSignのAPIにもアクセスできません（macOSで確認済み）。WebFetchからもAPIにはアクセスできません。ただし、以下は防止できません。

• トークンの読み取り。 Keychain内のトークンは、サンドボックス内であってもsecurity find-generic-passwordで読み取れます。これはファイルではなく、システムサービスに問い合わせるためです。-eで渡したトークンは~/.claude.jsonに保存されます。エージェントはトークンを確認できますが、シェルコマンドやWebFetchからZapSignに対して使用することはできません。
• サンドボックスの外で実行を許可したコマンド。 サンドボックス内でコマンドが失敗すると、Claudeはサンドボックスなしでの実行を求めることがあります（"Bash command (unsandboxed)"）。承認すると、これらの制限なしで実行されます。"allowUnsandboxedCommands": falseを設定すると、この選択肢は表示されなくなります。
• サンドボックスの外で実行されるコード。 MCPサーバーやフックなどが該当します。エージェントにそれらのファイルの編集を許可すると、動作を変更される可能性があります。

その他のクライアント

このサーバーはstdioでプレーンなMCPを使用するため、どのクライアントでも動作します。requiresUserInteractionマークを尊重するのはClaude Codeのみです。そのため、ほかのクライアントには読み取りのみが提示され、書き込みが呼び出された場合は拒否されます。

本番環境への書き込み

prodが読み取り専用なのは意図的です。本番環境に書き込むには、bin/zapsign-mcp.jsのENVIRONMENTSからreadOnly: trueを削除してください。

開発

npm test

テストからZapSignやKeychainにアクセスすることはありません。tests/zapsign-collection.jsonには、サーバーにツールが必要なすべてのリクエストが記載されています。Postmanコレクションに含まれるリクエストと、ドキュメントにのみ記載されているリクエストです。

リリース

1. プルリクエストで、package.json、server.json（2か所）、README の npx コマンドに新しいバージョンを設定します。すべてのバージョンが一致するまで、テストは失敗します。
2. マージ後、タグを v とそのバージョン（例：v1.0.1）にした GitHub リリースを公開します。
3. publish ワークフローはタグとバージョンを照合し、テストを実行してから、npm の信頼された公開機能（トークン不要）を使ってバージョンを npm にステージングします。
4. npmjs.com で 2FA を使ってステージングされたバージョンを承認します。承認されると公開され、ワークフローによって MCP Registry に登録されます。承認を待つ時間は1時間です。それ以降に承認し、mcp-registry ジョブを再実行してください。

ライセンス

MIT