UniOne

unione-mcp

适用于 UniOne（https://docs.unione.io）的官方 Model Context Protocol 服务。它让 AI 助手（Claude、ChatGPT、Cursor、Windsurf、VS Code、Cline 及任何其他 MCP 客户端）能够使用你的 UniOne 账户：发送邮件、管理发件人域名、模板、webhook、抑制列表、事件转储、标签和项目。包含 32 个工具，每个工具对应一次公开 UniOne Web API 调用。

有两种使用方式：

• 远程 — 托管在 https://mcp.unione.io/mcp 的服务。无需安装：将 URL 添加到客户端，然后通过 OAuth 登录 UniOne。
• 本地 — 服务通过 stdio 在你的计算机上运行（npx、Docker 或二进制文件），并使用你设置到 UNIONE_API_KEY 中的 API 密钥。

远程服务（OAuth）

URL：https://mcp.unione.io/mcp

首次使用时，客户端会打开 UniOne 登录页面；你批准访问后，客户端会保存令牌。你可以随时在 UniOne 账户中撤销令牌。

Claude Code

claude mcp add --transport http unione https://mcp.unione.io/mcp

Claude Desktop / claude.ai — 设置 → 连接器 → 添加自定义连接器，URL https://mcp.unione.io/mcp。

Cursor、Windsurf、Cline、VS Code 及其他使用 mcpServers 配置的客户端：

{
  "mcpServers": {
    "unione": {
      "type": "http",
      "url": "https://mcp.unione.io/mcp"
    }
  }
}

不支持 OAuth 的客户端可以改用 API 密钥：添加请求头 Authorization: Bearer <UniOne API key>。

本地服务（API 密钥）

在 UniOne 账户中获取 API 密钥：账户密钥可访问整个账户，项目密钥只能访问其所属项目。服务会从 UNIONE_API_KEY 读取密钥。

npx（Node.js 18+；首次运行时会下载适用于你平台的二进制文件）：

{
  "mcpServers": {
    "unione": {
      "command": "npx",
      "args": ["-y", "unione-mcp"],
      "env": { "UNIONE_API_KEY": "<your API key>" }
    }
  }
}

Docker：

{
  "mcpServers": {
    "unione": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "UNIONE_API_KEY", "ghcr.io/unione-repo/unione-mcp", "stdio"],
      "env": { "UNIONE_API_KEY": "<your API key>" }
    }
  }
}

二进制文件 — 从 Releases 下载 unione-mcp-<os>-<arch>，使其可执行并将其放入 PATH 中（或运行 go install github.com/unione-repo/unione-mcp/cmd/unione-mcp@latest）：

{
  "mcpServers": {
    "unione": {
      "command": "unione-mcp",
      "args": ["stdio"],
      "env": { "UNIONE_API_KEY": "<your API key>" }
    }
  }
}

Claude Code，一行配置：

claude mcp add unione --env UNIONE_API_KEY=<your API key> -- npx -y unione-mcp

询问 "显示我的 UniOne 账户"，即可检查连接：助手会调用 get_account。

工具

每个工具都有一个类别，并作为 MCP 注解发送给客户端：

• read — 仅读取（readOnlyHint）；
• write — 创建或更改内容，不会丢失任何内容（destructiveHint: false）；
• dangerous — 永久删除或覆盖内容，或无法撤销（destructiveHint: true）。 客户端会在调用此类工具前征求你的确认。

区域	工具	功能	类别
账户	get_account	获取 UniOne 账户信息	read
域名	list_domains	列出发件人域名	read
域名	get_dns_records	添加域名 / 获取其 DNS 记录	write
域名	validate_domain	检查域名 DNS 记录	read
域名	delete_domain	删除发件人域名	dangerous
域名	get_sandbox_domain	获取沙盒域名	write
已确认邮箱	list_confirmed_emails	列出已确认的邮箱	read
已确认邮箱	add_confirmed_email	添加已确认的邮箱	write
已确认邮箱	delete_confirmed_email	删除已确认的邮箱	dangerous
发送	send_email	发送邮件（计费）	dangerous
模板	list_templates	列出模板	read
模板	get_template	获取模板	read
模板	set_template	创建或覆盖模板	dangerous
模板	delete_template	删除模板	dangerous
Webhook	list_webhooks	列出 Webhook	read
Webhook	get_webhook	获取 Webhook	read
Webhook	set_webhook	创建或覆盖 Webhook	dangerous
Webhook	delete_webhook	删除 Webhook	dangerous
抑制列表	get_suppression	获取某个地址的抑制状态	read
抑制列表	list_suppressions	列出抑制项	read
抑制列表	set_suppression	屏蔽某个地址	dangerous
抑制列表	delete_suppression	解除对某个地址的屏蔽	dangerous
验证	validate_email	验证邮箱地址（计费）	write
事件转储	request_event_dump	请求事件转储	write
事件转储	get_event_dump	获取事件转储	read
事件转储	delete_event_dump	删除事件转储	dangerous
标签	list_tags	列出标签	read
标签	delete_tag	删除标签	dangerous
项目	list_projects	列出项目	read
项目	create_project	创建项目	write
项目	update_project	更新项目	dangerous
项目	delete_project	删除项目	dangerous

send_email 会发送真实邮件，且无法撤回。validate_email 会按地址计费。会触及账户以外资源的工具——send_email 和 add_confirmed_email 会向某个地址发送邮件，set_webhook 会将 UniOne 指向某个 URL，validate_email 会探测邮箱——会通过 openWorldHint: true 标明这一点。

只读和禁发模式

两个开关可以缩减本地服务的工具列表：

变量	效果
MCP_READ_ONLY=1	只列出 read 工具：助手无法更改账户
MCP_DISABLE_SEND=1	不列出 send_email：助手无法发送邮件

"env": { "UNIONE_API_KEY": "<your API key>", "MCP_READ_ONLY": "1" }

使用 Docker 时，env 只会作用于 docker 进程：请在镜像名称前使用容器自己的 -e，将开关传入容器。

"args": ["run", "-i", "--rm", "-e", "UNIONE_API_KEY", "-e", "MCP_READ_ONLY", "ghcr.io/unione-repo/unione-mcp", "stdio"],
"env": { "UNIONE_API_KEY": "<your API key>", "MCP_READ_ONLY": "1" }

这些开关只能防止模型出错，无法约束密钥所有者：同一个密钥仍可直接用于 Web API。如需硬性限制，请使用项目 API 密钥。

配置

所有配置均通过环境变量设置；也会读取工作目录中的 .env 文件。 .env.example 列出了所有配置项。每个值都会在启动时进行验证。

变量	用途
UNIONE_API_KEY	本地模式：所有工具使用的 API 密钥
UNIONE_API_URL	Web API 基础 URL，默认值为 https://api.unione.io/en/transactional/api/v1
MCP_TRANSPORT	http（默认）或 stdio；unione-mcp stdio 也会设置此项
MCP_READ_ONLY、MCP_DISABLE_SEND	参见上文
AUTH_MODE	自托管 http 模式：api_key（默认）或 oauth
AUTHORIZATION_SERVER_URL、OAUTH_SCOPES、OAUTH_TOKEN_PREFIX、MCP_PUBLIC_URL	自托管 oauth 模式。OAUTH_TOKEN_PREFIX 的默认值为 uoat_。
LISTEN_HOST、PORT	自托管 http 模式的监听器（默认：所有网络接口，从 3000 开始使用第一个可用端口）
UPSTREAM_TIMEOUT、UPSTREAM_MAX_BODY_BYTES、MCP_MAX_REQUEST_BYTES	Web API 调用限制和 /mcp 请求体大小上限
LOG_LEVEL、LOG_FORMAT	debug、info、warn、error；text 或 json，始终输出到 stderr

API 密钥、Authorization 标头和 Web API 响应体均不会被记录。

文档

• UniOne API：https://docs.unione.io
• 使用 AI Agent 安装：llms-install.md
• 报告漏洞：SECURITY.md
• 问题和拉取请求：CONTRIBUTING.md

开发

go build -o bin/unione-mcp ./cmd/unione-mcp
go test ./internal/... ./cmd/...                     # unit tests, no network

# acceptance: the real binary over HTTP and stdio against a WireMock stand-in of the API
docker run -d --rm -p 8081:8081 wiremock/wiremock:3.4.1 --local-response-templating --port 8081
E2E_WIREMOCK_URL=http://localhost:8081 go test -tags=integration ./tests/...

许可证

MIT