内容
# eCardWidget MCP 服务器
[](https://www.npmjs.com/package/ecardwidget-mcp)
**eCardWidget** 的官方 [模型上下文协议](https://modelcontextprotocol.io) 服务器。让 AI 助手（Claude Desktop、Claude Code、Cursor 等）在您的 eCardWidget 账户中工作 — 搜索和发送电子贺卡、管理目录、列出活动/小工具/自动化 — 使用您**自行生成和范围限定**的 **API 密钥**。
> **助手只能执行 API 密钥允许的操作。** 服务器启动时，会询问 API 密钥允许执行的操作，并仅注册该密钥范围内的工具。所有范围强制执行、限流和审计都在服务器端进行。
## 快速开始
首先，在您的 eCardWidget 仪表盘中**生成范围限定的 API 密钥**：**设置 → 开发者 → API 密钥**。仅授予您希望助手访问的区域。然后选择适合您的客户端的安装方式：
### 选项 A — Claude Desktop（一键安装）
从 [最新版本](https://github.com/eCardWidget/ecardwidget-mcp/releases) 下载 `ecardwidget-mcp.mcpb` 并打开它。Claude Desktop 会显示一个安装对话框，**询问您的 API 密钥**（存储在您的操作系统密钥链中）— 无需配置文件，无需命令。
### 选项 B — 登录一次，然后输入短命令（Claude Code / Cursor / 任意客户端）
```bash
npx ecardwidget-mcp login # 提示输入密钥，验证并本地保存（0600）
claude mcp add ecardwidget -- npx -y ecardwidget-mcp # 命令中不包含密钥
```
服务器会自动读取保存的密钥。（`npx ecardwidget-mcp logout` 会删除它。）
### 选项 C — 将密钥放入客户端配置文件（手动）
```json
{
"mcpServers": {
"ecardwidget": {
"command": "npx",
"args": ["-y", "ecardwidget-mcp"],
"env": { "ECW_API_KEY": "您的_API_密钥" }
}
}
}
```
重启您的客户端。它会连接并显示您的密钥范围内的工具。优先级：显式的 `ECW_API_KEY` 环境变量始终优于保存的 `login` 凭证。
## 配置
| 变量名 | 是否必填 | 默认值 | 描述 |
| -------------- | -------- | ----------------------------- | -------------------------------------------- |
| `ECW_API_KEY` | 是 | — | 您的范围限定的 API 密钥（用作 Bearer token）。|
| `ECW_BASE_URL` | 否 | `https://app.ecardwidget.com` | 仅在自定义域名/测试时覆盖。 |
## 工具
所有工具都以 `ecw_*` 为前缀；只有您的密钥范围内的工具才会被注册。
- **自检：** `ecw_whoami`
- **电子贺卡：** `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`
破坏性工具（删除、发送活动）使用**两步确认** — 调用一次进行预览并获取一次性令牌，然后再次调用令牌以执行。删除自动化/活动和发送礼品卡活动需要在仪表盘中确认。
自然地提问，例如 *"从我们的 Thank-You 小工具向 grace@acme.com 发送生日贺卡"*。
## 安全
参见 [SECURITY.md](./SECURITY.md)。简而言之：最小权限范围的密钥、服务器端强制执行是真正的保证、破坏性操作需要两步确认，并且 API 密钥永远不会被记录。
## 开发
```bash
npm install
npm run build # tsup → dist/index.js
npm test # vitest
npm run inspector # MCP Inspector 对抗构建的服务器（需要 ECW_API_KEY）
```
## 许可证
MIT
