{
  "markdown": "# eCardWidget MCP Server\n\n[![npm](https://img.shields.io/npm/v/ecardwidget-mcp.svg)](https://www.npmjs.com/package/ecardwidget-mcp)\n\nThe official [Model Context Protocol](https://modelcontextprotocol.io) server for\n**[eCardWidget](https://www.ecardwidget.com)**. Let an AI assistant (Claude Desktop, Claude Code, Cursor,\n…) work in your eCardWidget account — search and send eCards, manage your directory, list\ncampaigns/widgets/automations — using an **API key you generate and scope yourself**.\n\n> **The assistant can only ever do what your API key permits.** On startup the server asks the API what\n> the key is allowed to do and registers **only** the tools that key is scoped for. All scope enforcement,\n> throttling, and auditing happen server-side.\n\n## Quick start\n\nFirst, **generate a scoped API key** in your eCardWidget dashboard: **Settings → Developers → API Keys**.\nGrant only the areas you want the assistant to touch. Then pick whichever install fits your client:\n\n### Option A — Claude Desktop (one click)\n\nDownload `ecardwidget-mcp.mcpb` from the [latest release](https://github.com/eCardWidget/ecardwidget-mcp/releases)\nand open it. Claude Desktop shows an install dialog that **asks you for your API key** (stored in your OS\nkeychain) — no config files, no commands.\n\n### Option B — Sign in once, then a short command (Claude Code / Cursor / any client)\n\n```bash\nnpx ecardwidget-mcp login          # prompts for your key, verifies + saves it locally (0600)\nclaude mcp add ecardwidget -- npx -y ecardwidget-mcp   # no key in the command\n```\n\nThe server reads the saved key automatically. (`npx ecardwidget-mcp logout` removes it.)\n\n### Option C — Put the key in your client config (manual)\n\n```json\n{\n  \"mcpServers\": {\n    \"ecardwidget\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"ecardwidget-mcp\"],\n      \"env\": { \"ECW_API_KEY\": \"YOUR_API_KEY\" }\n    }\n  }\n}\n```\n\nRestart your client. It connects and shows the tools your key is scoped for. Precedence: an explicit\n`ECW_API_KEY` env var always wins over the saved `login` credential.\n\n## Configuration\n\n| Variable       | Required | Default                       | Description                                  |\n| -------------- | -------- | ----------------------------- | -------------------------------------------- |\n| `ECW_API_KEY`  | yes      | —                             | Your scoped API key (used as a Bearer token).|\n| `ECW_BASE_URL` | no       | `https://app.ecardwidget.com` | Override only for a custom domain / testing. |\n\n## Tools\n\nAll tools are namespaced `ecw_*`; only those your key is scoped for are registered.\n\n- **Introspection & discovery:** `ecw_whoami`, `ecw_describe_fields` (what fields you can set on a\n  widget / eCard / campaign / automation — synced from the OpenAPI spec)\n- **eCards:** `ecw_search_ecards`, `ecw_get_widget_ecards`, `ecw_create_ecard` (image via URL or base64),\n  `ecw_send_ecard`, `ecw_delete_ecard`\n- **Directory:** `ecw_list_team_members`, `ecw_find_team_member`, `ecw_upsert_team_member`,\n  `ecw_import_team_members`, `ecw_deactivate_team_member`, `ecw_delete_team_member`\n- **Widgets:** `ecw_list_widgets`, `ecw_create_widget`, `ecw_duplicate_widget`, `ecw_delete_widget`\n- **Automations:** `ecw_list_automations`, `ecw_create_automation` (birthday / anniversary / onboarding)\n- **Campaigns:** `ecw_list_campaigns`, `ecw_create_campaign` (draft), `ecw_send_campaign`\n\nDestructive tools (delete, send campaign) use a **two-step confirmation** — call once for a preview + a\none-time token, then again with the token to execute. Deleting automations/campaigns and sending\ngift-card campaigns require confirmation in the dashboard.\n\n### Guided flows (prompts)\n\nThe server ships **prompts** — guided, multi-step flow templates your client surfaces as\nslash-commands/suggestions: `run_campaign`, `setup_automation`, `spin_up_widget`, `import_directory`\n(each shown only if your key is scoped for it). It also hands the assistant a compact overview of the\nobject model and the core flows at connect, so it understands how widgets, eCards, campaigns,\nautomations, and the directory fit together.\n\nAsk naturally, e.g. *\"Send a birthday eCard from our Thank-You widget to grace@acme.com\"*.\n\n## Security\n\nSee [SECURITY.md](./SECURITY.md). In short: least-privilege scoped keys, server-side enforcement is the\nreal guarantee, destructive actions require a two-step confirmation, and the API key is never logged.\n\n## Development\n\n```bash\nnpm install\nnpm run build          # tsup → dist/index.js\nnpm test               # vitest\nnpm run inspector      # MCP Inspector against the built server (needs ECW_API_KEY)\n```\n\n## License\n\nMIT\n",
  "bytes": 4649,
  "sha": "d6fa8fdb3875db5cb574b72af1f259185d55dadd9f0c447695435f2c1e4bb99c",
  "repo_slug": "ecardwidget/ecardwidget-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ecardwidget_ecardwidget_mcp_e5534c94/readme"
}