SpacePost

@spacepost/mcp

AI アシスタントに SpacePost API 全体を提供する MCP サーバーです。API リファレンスの各エンドポイントに対して 1 つのツールを用意し、OpenAPI ドキュメントから生成されています。新しい API 機能は自動的に MCP ツールになります。ドキュメント：https://docs.spacepost.dev/tools/mcp/

SpacePost は、Amazon SES 上で動作する Resend 互換のトランザクションメール API（EU 企業）で、SMTP リレーとこの MCP サーバーを提供しています。

利用方法は 2 つあります。

• ホスト版：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 に送信され、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 個のツールは、名前を維持します。
• 入力：パスパラメーター（snake_case：audience_id、id_or_email）、クエリパラメーター、ヘッダーパラメーター（Idempotency-Key → idempotency_key）、トップレベルの JSON ボディフィールドを含む、フラットな JSON Schema オブジェクトを 1 つ使用します。ボディフィールド名がパラメーター名と重複する場合は body_<field> として公開されます。オブジェクト以外のボディ（バッチ配列）は body として公開されます。$ref／allOf はインライン化され、列挙型、形式、パターン、制約値、デフォルト値、説明は保持されます。
• 説明：仕様の概要と説明、厳選された補足情報、必要な権限、HTTP ルートが含まれます。
• アノテーション：GET → readOnlyHint、DELETE → destructiveHint、GET／PUT／DELETE → idempotentHint となります。操作ごとに上書きできます。
• 結果：API の JSON（テキスト + structuredContent）です。エラーは、Resend 形式の { statusCode, name, message } ボディとヒントを含む isError: true になります。

ツールの調整

ツールは 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.