Winnr

winnr-mcp

适用于 Winnr 冷邮件基础设施 API 的 MCP 服务。

让 Claude（网页、移动端和桌面端）、ChatGPT、Claude Code、Cursor、Windsurf、VS Code （Copilot）以及任何其他 MCP 客户端通过自然语言管理域名、 邮箱、预热、收件箱、预热域名市场和 Webhook。

55 个工具，其中 26 个只读，另有 8 个资源和 5 个提示词手册。

两种运行方式：

	托管（推荐）	本地
端点	https://mcp.winnr.app/mcp	通过 stdio 运行 uvx winnr-mcp
身份验证	使用 Winnr 登录（OAuth 2.1 + PKCE）	配置文件中的 API 令牌
安装	无需安装	uv，以及每个应用各自的配置文件
适用范围	claude.ai 网页版/移动版、ChatGPT 和所有桌面客户端	仅限桌面客户端

无论选择哪种方式，均可在此设置： app.winnr.app/mcp。

---

托管服务

将 https://mcp.winnr.app/mcp 添加为自定义连接器 / 远程 MCP 服务。客户端 会自行注册（RFC 7591），并将你带到 Winnr 登录，然后你可以选择它能执行的操作：

范围	授予权限
read	列出和检查所有内容。始终授予。
write	创建、更改、发送、删除。
purchase	消费资金：购买域名、购买预热域名、启用预热。

权限范围相互包含（purchase ⊃ write ⊃ read），会话只能看到 其权限范围允许使用的工具。每项授权都由一个常规 API 令牌提供支持，令牌名称为 MCP · <client>，因此它会显示在控制面板的 API 页面中；在该页面撤销令牌后，助手 便会失去访问权限。

# Claude Code, hosted
claude mcp add --scope user --transport http winnr https://mcp.winnr.app/mcp

---

快速开始（本地）

1. 获取令牌

前往 app.winnr.app/mcp（或选择 API → Create Token）。令牌以 wnr_ 开头。如果你只需要报告和回复分类，请选择只读：届时，所有会 创建、发送、购买或删除内容的工具都会对助手隐藏。添加 WINNR_NO_PURCHASES=true（或 --no-purchases），即可保留完整写入权限，同时隐藏 会产生费用的 4 个工具。

2. 安装 uv

服务通过 uvx 运行，因此只需安装一次 uv：

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh      # or: brew install uv
# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

没有 uv？运行 pip install winnr-mcp，并改用 "command": "winnr-mcp"，不带任何参数。

3. 将服务添加到客户端

Claude Desktop

依次选择 Settings → Developer → Edit Config，然后粘贴以下内容（macOS： ~/Library/Application Support/Claude/claude_desktop_config.json，Windows： %APPDATA%\Claude\claude_desktop_config.json）。完全退出并重新打开 Claude。

{
  "mcpServers": {
    "winnr": {
      "command": "uvx",
      "args": ["winnr-mcp"],
      "env": { "WINNR_API_TOKEN": "wnr_your_token_here" }
    }
  }
}

Claude Code

claude mcp add --scope user winnr -e WINNR_API_TOKEN=wnr_your_token_here -- uvx winnr-mcp

然后，在 Claude Code 中运行 /mcp，即可看到 Winnr 已连接。可选的引导式工作流 （/winnr setup、/winnr health、/winnr export）由 winnr-claude-skills 提供：

curl -sL https://raw.githubusercontent.com/winnr-app/winnr-claude-skills/main/install.sh | bash

Cursor

~/.cursor/mcp.json（全局）或 .cursor/mcp.json（项目）——与 Claude Desktop 使用相同的 JSON。服务运行时，Settings → MCP 中的 Winnr 旁会显示绿色圆点。

Windsurf

~/.codeium/windsurf/mcp_config.json——使用相同的 JSON。在 Settings → Cascade → MCP Servers 中刷新。

VS Code（Copilot Agent 模式）

.vscode/mcp.json：

{
  "servers": {
    "winnr": {
      "type": "stdio",
      "command": "uvx",
      "args": ["winnr-mcp"],
      "env": { "WINNR_API_TOKEN": "wnr_your_token_here" }
    }
  }
}

4. 试用

我的 Winnr 账户中有哪些内容？还剩多少容量？

助手会调用 winnr_get_account 和 winnr_get_usage。使用令牌后， app.winnr.app/mcp 页面会显示已连接。

配置

来源	变量 / 标志	描述
环境变量	WINNR_API_TOKEN	必需。 你的 Winnr API 令牌（wnr_*）
环境变量	WINNR_API_URL	API 基础 URL（默认 https://api.winnr.app；转售商使用自己的主机）
环境变量	WINNR_TIMEOUT	HTTP 超时时间（秒，默认 30；购买操作使用 60）
环境变量	WINNR_READ_ONLY	设为 true 时仅注册读取工具，即使使用的是读写令牌
环境变量	WINNR_NO_PURCHASES	设为 true 时保留写入权限，但隐藏四个资金相关工具
环境变量	WINNR_CONFIRM_SECRET	购买确认令牌的 HMAC 密钥（在托管服务上自动设置）
CLI	--token、--api-url、--timeout、--read-only、--no-purchases、--version	覆盖环境变量

CLI 参数的优先级高于环境变量。

启动时，服务会调用 GET /v1/account。令牌无效时会立即退出并显示明确的提示（启动后每次调用都失败的服务更糟）。如果令牌为只读，写入工具会自动隐藏——无需设置标志。

花钱始终分两步

四个会从银行卡扣款的工具——winnr_purchase_domains、 winnr_purchase_prewarmed、winnr_purchase_prewarmed_batch、 winnr_enable_warming——首次调用时绝不会扣款。它们会返回一份实时报价（重新检查可用性、 确切价格和每月总额），以及一个有效期为 10 分钟的 confirmation_token。助手会显示报价、征得明确同意，然后携带令牌再次调用。届时会重新计算报价，并基于该报价生成 HMAC 令牌；因此，如果价格变动或域名已售出，购买操作会被拒绝并返回最新报价，而不会意外扣款。

如何引导助手

服务会向客户端发送 instructions（大多数宿主会将其放入系统 提示词中），每个工具也都带有 MCP 注释（readOnlyHint、destructiveHint、 idempotentHint），以便宿主在适当时机请求确认。说明涵盖：

• ID 和异步任务（job_id → 轮询 winnr_get_job）
• 四个会从银行卡扣款的工具（购买域名、购买预热邮箱 ×2、启用预热），以及先征得明确同意并确认确切价格的规则。下单前会重新检查域名是否可用及其价格；如有任何变化，就会拒绝下单，因此确认的总额就是实际扣款总额
• 超时后，未经检查 winnr_list_jobs，绝不重试购买
• 域名命名规范（类似品牌名称；不使用 outreach/blast/bulk 等词）
• 冷邮件比例（每个域名使用 2–5 个邮箱，预热 2–3 周，每日发送量保持适度）

它还提供资源（宿主可附加到对话中的只读记录： winnr://account、winnr://usage、winnr://domains、winnr://domains/{id}、 winnr://domains/{id}/dns-records、winnr://domains/{id}/dns-status、 winnr://warming/overview、winnr://jobs/{id}）和提示词——可参数化的 操作手册：winnr_setup_infrastructure、winnr_health_check、winnr_reply_triage、 winnr_connect_own_domain、winnr_scale_up。

工具

权限是工具所需的令牌范围。所有令牌都可以查看读取工具。

账户、任务、导出

工具	描述	权限
winnr_get_account	账户、套餐、限制，以及调用令牌的权限范围	read
winnr_get_usage	域名／电子邮件用户／预热地址与限制的使用情况	read
winnr_list_jobs	最近的异步任务（可按状态／类型筛选）	read
winnr_get_job	单个任务的状态、进度、结果和错误	read
winnr_wait_for_job	阻塞等待任务完成，并流式传输进度通知	read
winnr_list_export_formats	支持的 CSV 格式	read
winnr_export_email_users	凭据 CSV（链接有效期为 15 分钟），支持 22 种序列器格式	write

域名

工具	描述	权限
winnr_list_domains	列出域名（分页，可选状态筛选：complete、pending、…）	read
winnr_get_domain	单个域名的 DNS 状态和实时健康状况	read
winnr_search_domains	查询一个名称的可用性和价格	read
winnr_search_domains_bulk	查询最多 100 个名称的可用性和价格	read
winnr_get_dns_status	配置／传播状态（MX、SPF、DKIM、DMARC）	read
winnr_get_dns_records	手动 DNS 域名需要添加的记录	read
winnr_check_dns_provider	查询域名当前托管 DNS 的位置（每次调用最多 20 个）	read
winnr_purchase_domains	购买并设置域名（报价 → 确认，将扣款）	purchase
winnr_setup_domain	重新运行 DNS／邮件配置，添加邮箱／重定向	write
winnr_connect_domains	接入自有域名（名称服务器、手动 DNS 或 Cloudflare 令牌）	write
winnr_check_nameservers	验证 NS 更改；自动排入配置任务	write
winnr_verify_dns	实时验证手动 DNS 记录	write
winnr_tag_domains	为最多 50 个域名添加／移除／设置标签	write
winnr_delete_domain	删除域名及其邮箱（不可逆操作）	write

邮箱（电子邮件用户）

工具	描述	权限
winnr_list_email_users	列出邮箱，可按域名筛选	read
winnr_get_email_user	单个邮箱的 IMAP/SMTP 详情	read
winnr_create_email_user	创建一个邮箱（异步任务）	write
winnr_bulk_create_email_users	在一个域名上创建最多 100 个邮箱	write
winnr_update_email_user	重命名或设置密码	write
winnr_delete_email_user	删除一个邮箱（不可逆操作）	write

收件箱

工具	描述	权限
winnr_list_inbox	所有邮箱中的邮件；默认隐藏预热邮件	read
winnr_get_message_body	根据 uid + mailbox 获取完整正文（截断至 10k 个字符）	read
winnr_send_email	从邮箱发送邮件，支持线程标头	write
winnr_refresh_inbox	触发同步	write
winnr_delete_message	删除一封邮件（不可逆操作）	write

预热

工具	描述	权限
winnr_list_warming	列出所有预热邮箱及其健康状况／收件箱率	read
winnr_get_warming_overview	汇总统计数据和预估月费用	read
winnr_get_warming_metrics	单个邮箱的每日数据序列	read
winnr_enable_warming	启用；emails_per_day 为 1–20，rampup_speed（报价 → 确认，$0.60/邮箱/月）	purchase
winnr_disable_warming	禁用并停止计费	write
winnr_pause_warming / winnr_resume_warming	暂时停止／重新启动	write
winnr_update_warming_settings	emails_per_day、rampup_enabled、rampup_speed	write

预热市场

工具	描述	权限
winnr_browse_prewarmed	可用的老域名和预热域名	读取
winnr_get_prewarmed_domain	单个列表项的逐地址健康状况	读取
winnr_check_prewarmed_blocklist	实时黑名单检查（9 个列表）	读取
winnr_list_my_prewarmed	已购买的预热域名	读取
winnr_purchase_prewarmed	购买一个域名，$3/地址/月（报价 → 确认，会扣款）	购买
winnr_purchase_prewarmed_batch	一次扣款购买最多 25 个域名（报价 → 确认，会扣款）	购买
winnr_cancel_prewarmed	取消并退还域名（破坏性操作）	写入

Webhook

工具	描述	权限
winnr_list_webhooks	含状态和健康状况的端点	读取
winnr_get_webhook_deliveries	最近的投递尝试	读取
winnr_create_webhook	创建（响应中包含签名密钥）	写入
winnr_update_webhook	更改 URL/事件/描述/状态	写入
winnr_test_webhook	发送 test.ping	写入
winnr_rotate_webhook_secret	轮换密钥（旧密钥 24 小时内仍有效）	写入
winnr_get_webhook_secret	读取签名密钥（敏感信息；只读令牌不可见）	写入
winnr_delete_webhook	删除（破坏性操作）	写入

错误

每个工具都会返回 JSON。失败时的格式如下：

{ "error": { "message": "Payment required: …", "status_code": 402, "code": "payment_method_required" } }

这样 Agent 就可以根据 code 进行分支处理。只读请求返回的 403 会说明令牌缺少写入权限；读取请求遇到 429 时会自动重试一次。

安全性

• 令牌权限范围。 所有操作都以同一账户的身份执行，并受令牌权限限制。 在控制面板中撤销令牌后，助手会立即失去访问权限。
• 工具输出中不会出现密码。 凭据只会通过 winnr_export_email_users 导出，该工具会生成 15 分钟有效的预签名 CSV 链接，且需要读写令牌。
• 不会记录任何内容。 令牌通过 bearer 标头发送，不会被打印；服务只会向 stderr 写入一行启动信息。
• 速率限制采用 API 的限制（Startup 为 300 次请求/分钟，Enterprise 为 500 次）。当窗口期内剩余请求少于 10 次时，服务会发出警告。

开发

git clone https://github.com/winnr-app/winnr-mcp.git
cd winnr-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest          # 124 tests, all HTTP mocked (incl. the full OAuth flow)
ruff check src tests
WINNR_API_TOKEN=wnr_xxx python -m winnr_mcp   # run locally over stdio

# the hosted server, locally
pip install -e ".[remote]"
uvicorn --factory winnr_mcp.remote.app:create_app --port 8000

部署托管服务

python scripts/deploy_remote.py 会在 AWS 中配置所有资源（用于 OAuth 状态的 DynamoDB 表、SSM 密钥、arm64 Lambda + layer、HTTP API、ACM 证书、mcp.winnr.app 域名和 Route53 别名），并验证部署。

许可证

MIT