SpacePost

@spacepost/mcp

一个 MCP 服务，为 AI 助手提供完整的 SpacePost API：根据 API 参考文档中的 OpenAPI 文档生成，每个端点对应一个工具。新的 API 功能会自动成为 MCP 工具。文档：https://docs.spacepost.dev/tools/mcp/

SpacePost 是一款兼容 Resend、基于 Amazon SES 的事务邮件 API（欧盟公司），提供 SMTP 中继 和此 MCP 服务。

有两种使用方式：

• 托管方式：https://api.spacepost.dev/mcp（Streamable HTTP），使用 Authorization: Bearer sp_live_...。无需安装。
• 本地方式（此软件包）：npx -y @spacepost/mcp，使用 stdio。规范已打包，因此可离线启动。

在 SpacePost 控制面板中创建 API 密钥。在官方 MCP Registry 中，该服务的名称为 dev.spacepost/mcp；在 npm 上的名称为 @spacepost/mcp。

配置

环境变量
SPACEPOST_API_KEY	必填。助手拥有与此密钥完全相同的权限（sending_access 密钥只能发送邮件）。
SPACEPOST_BASE_URL	可选，默认值为 https://api.spacepost.dev
SPACEPOST_DEFAULT_FROM	可选发件人（例如 Acme <[email protected]>），在 send_email 未设置 from 时使用
SPACEPOST_READ_ONLY	true = --read-only
SPACEPOST_TOOLSETS	= --toolsets
SPACEPOST_PERMISSION	= --permission

标志
--read-only	仅使用 GET 端点的工具
--toolsets a,b	仅使用这些 API 区域（OpenAPI 标签）：emails、domains、apikeys、webhooks、audiences、contacts、broadcasts、suppressions、tenants
--permission sending_access	仅使用仅发送密钥可用的工具（具有 x-permission: sending_access 的操作）
--list-tools	输出给定选项对应的工具，然后退出
--help、--version

托管端点接受相同的选项作为查询参数：/mcp?read_only=true&toolsets=emails,domains。它会根据调用者的密钥确定权限筛选条件：sending_access 密钥在 tools/list 中只能看到发送工具。MCP 不会阻止其他工具；调用这些工具会向 API 发起请求，API 会像处理 REST 请求一样返回 restricted_api_key。

Claude Code

# hosted
claude mcp add --transport http spacepost https://api.spacepost.dev/mcp --header "Authorization: Bearer sp_live_..."
# local
claude mcp add spacepost -e SPACEPOST_API_KEY=sp_live_... -e SPACEPOST_DEFAULT_FROM="Acme <[email protected]>" -- npx -y @spacepost/mcp

Cursor（~/.cursor/mcp.json 或 .cursor/mcp.json）

{
  "mcpServers": {
    "spacepost": { "url": "https://api.spacepost.dev/mcp", "headers": { "Authorization": "Bearer sp_live_..." } }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "spacepost": {
      "command": "npx",
      "args": ["-y", "@spacepost/mcp"],
      "env": { "SPACEPOST_API_KEY": "sp_live_...", "SPACEPOST_DEFAULT_FROM": "Acme <[email protected]>" }
    }
  }
}

Docker

docker build -t spacepost-mcp .
docker run -i --rm -e SPACEPOST_API_KEY=sp_live_... spacepost-mcp

此镜像从本仓库的源代码构建服务，并以非 root 用户通过 stdio 运行。密钥在运行时从环境变量读取，不会写入镜像。

工具的构建方式

• 名称：operationId 的 snake_case 形式（sendEmail → send_email，getBroadcastReadiness → get_broadcast_readiness）。0.1 版的 12 个手写工具保留原名。
• 输入：一个扁平的 JSON Schema 对象，包含路径参数（snake_case：audience_id、id_or_email）、查询参数、标头参数（Idempotency-Key → idempotency_key）以及顶层 JSON 请求体字段。与参数名称冲突的请求体字段会以 body_<field> 的形式公开；非对象请求体（批处理数组）则以 body 的形式公开。$ref/allOf 会内联；枚举、格式、模式、边界、默认值和描述均予以保留。
• 描述：规范中的摘要和描述、精选补充内容、所需权限以及 HTTP 路由。
• 注解：GET → readOnlyHint；DELETE → destructiveHint；GET/PUT/DELETE → idempotentHint；可按操作覆盖。
• 结果：API 的 JSON（文本 + structuredContent）。错误：返回 isError: true，并包含 Resend 风格的 { statusCode, name, message } 错误正文和提示。

调整工具

工具遵循 API 的 OpenAPI 文档。操作包含以下扩展（由 SpacePost 在规范中设置）：

x-mcp: { hidden: false, description: "Extra guidance for agents.", destructive: true, idempotent: true, openWorld: true }
x-permission: sending_access # only on operations a sending_access key may call

src/overlay.ts（按 operationId 索引）保存少量精选描述，内容侧重于如何更好地使用工具，而非 API 本身；若同一字段在两处都有设置，则以 x-mcp 为准。

开发

bun install
bun run build     # dist/index.js, spec included
bun test
bun run generate  # refresh src/generated/openapi.json from https://api.spacepost.dev/openapi.json

欢迎提交问题和拉取请求。安全问题请发送至：[email protected]。

0.2 版的破坏性变更：结果改为原始 API JSON，不再是简短的文本摘要；verify_domain 返回验证响应（如需获取新状态，请调用 get_domain）。

许可证

MIT，详见 LICENSE。© Studio 404 d.o.o.