ecardwidget-mcp

eCardWidget MCP サーバー

eCardWidget の公式 Model Context Protocol サーバーです。 AI アシスタント（Claude Desktop、Claude Code、Cursor、 …）が eCardWidget アカウントで作業できます。eカードの検索と送信、ディレクトリの管理、キャンペーン／ウィジェット／自動化の一覧表示を、自分で生成し、権限範囲を設定した API キーを使って行えます。

アシスタントが実行できる操作は、API キーで許可されたものに限られます。 起動時にサーバーは API にキーの権限を問い合わせ、そのキーに権限が設定されているツールのみを登録します。権限の適用、スロットリング、監査はすべてサーバー側で行われます。

クイックスタート

まず、eCardWidget のダッシュボードで権限範囲を設定した API キーを生成します：Settings → Developers → API Keys。 アシスタントに操作させたい領域だけを許可してください。その後、クライアントに合ったインストール方法を選びます。

オプション A — Claude Desktop（ワンクリック）

最新リリースから ecardwidget-mcp.mcpb をダウンロードして開きます。Claude Desktop にインストールダイアログが表示され、API キーの入力を求められます（OS のキーチェーンに保存されます）。設定ファイルもコマンドも必要ありません。

オプション B — 一度サインインして、短いコマンドを実行（Claude Code／Cursor／任意のクライアント）

npx ecardwidget-mcp login          # prompts for your key, verifies + saves it locally (0600)
claude mcp add ecardwidget -- npx -y ecardwidget-mcp   # no key in the command

サーバーは保存済みのキーを自動的に読み込みます。（npx ecardwidget-mcp logout で削除できます。）

オプション C — クライアントの設定にキーを記述（手動）

{
  "mcpServers": {
    "ecardwidget": {
      "command": "npx",
      "args": ["-y", "ecardwidget-mcp"],
      "env": { "ECW_API_KEY": "YOUR_API_KEY" }
    }
  }
}

クライアントを再起動します。接続後、キーに権限が設定されているツールが表示されます。優先順位：明示的に設定した ECW_API_KEY 環境変数は、保存済みの login 認証情報より常に優先されます。

設定

変数	必須	デフォルト	説明
ECW_API_KEY	はい	—	権限範囲を設定した API キー（Bearer トークンとして使用）。
ECW_BASE_URL	いいえ	https://app.ecardwidget.com	カスタムドメイン／テストの場合のみ上書きします。

ツール

すべてのツールには ecw_* という名前空間が付いており、キーに権限が設定されているもののみが登録されます。

• 情報確認と検出： ecw_whoami、ecw_describe_fields（ウィジェット／eカード／キャンペーン／自動化で設定可能なフィールド。OpenAPI 仕様と同期）
• eカード： ecw_search_ecards、ecw_get_widget_ecards、ecw_create_ecard（URL または base64 で画像を指定）、 ecw_send_ecard、ecw_delete_ecard
• ディレクトリ： ecw_list_team_members、ecw_find_team_member、ecw_upsert_team_member、 ecw_import_team_members、ecw_deactivate_team_member、ecw_delete_team_member
• ウィジェット： ecw_list_widgets、ecw_create_widget、ecw_duplicate_widget、ecw_delete_widget
• 自動化： ecw_list_automations、ecw_create_automation（誕生日／記念日／オンボーディング）
• キャンペーン： ecw_list_campaigns、ecw_create_campaign（下書き）、ecw_send_campaign

削除やキャンペーンの送信など、破壊的なツールでは2 段階の確認を使用します。最初に呼び出してプレビューと一度限りのトークンを取得し、次にそのトークンを指定して実行します。自動化／キャンペーンの削除やギフトカードキャンペーンの送信には、ダッシュボードでの確認が必要です。

ガイド付きフロー（プロンプト）

サーバーにはプロンプトが用意されており、クライアントにスラッシュコマンド／候補として表示される、複数ステップのガイド付きフローテンプレートです：run_campaign、setup_automation、spin_up_widget、import_directory（それぞれ、キーに権限が設定されている場合のみ表示されます）。また、接続時にオブジェクトモデルと主要なフローの概要を簡潔にアシスタントへ渡すため、ウィジェット、eカード、キャンペーン、自動化、ディレクトリの関係を理解できます。

たとえば、自然な言葉で依頼できます。「Thank-You ウィジェットから [email protected] に誕生日の eカードを送って」。

セキュリティ

SECURITY.mdを参照してください。要点としては、最小権限にスコープを限定したキーを使用し、実際の保証はサーバー側で適用します。破壊的な操作には2段階の確認が必要で、APIキーがログに記録されることはありません。

開発

npm install
npm run build          # tsup → dist/index.js
npm test               # vitest
npm run inspector      # MCP Inspector against the built server (needs ECW_API_KEY)

ライセンス

MIT