MCP 服务器

Bird MCP 服务器将 Bird API 以 Model Context Protocol 工具的形式暴露出来。支持的客户端包括 Claude Code、Cursor、VS Code、Codex、Claude、ChatGPT 和 Muse。它们可以通过 Bird 运行的每个渠道发送消息、配置这些渠道，以及查看你的工作区，无需复制 cURL 命令。你可以通过两种方式运行它，大多数人选择第一种：

托管模式 (mcp.bird.com)：只需一个 URL 和浏览器登录。无需安装任何东西，不需要 CLI，不需要 API 密钥。这是推荐方式。
本地 stdio 模式 (bird mcp)：工具在你的机器上通过 bird CLI 运行，适用于 shell 代理或自行运行的场景。

托管服务器不包含以下仅限 stdio 的工具：

auth_signup、auth_verify_email 和 auth_create_org：这些工具用于创建你的第一个凭据，在你能够向托管服务器进行身份验证之前使用。
compliance_attachments_upload：该工具读取本地文件路径。在托管服务器上，该路径会指向服务器的文件系统，可能上传错误的文件。

托管模式：连接到 `mcp.bird.com`

选择端点

大多数连接使用 https://mcp.bird.com。这是推荐端点：大多数 MCP 客户端已能从完整目录中自行搜索和选择工具。部分客户端不支持内部搜索工具，或对服务器可暴露的工具数量有硬性限制。/dynamic 专为这些客户端设计。

两个托管端点都使用 Streamable HTTP 和相同的 Bird OAuth 登录：

端点	客户端可见的工具	何时使用
`https://mcp.bird.com`	完整的托管工具目录	推荐大多数客户端使用，它们可在内部搜索和选择工具。同时支持 MCP Apps 小组件。
`https://mcp.bird.com/dynamic`	仅 `search` 和 `execute`	仅适用于不支持内部工具搜索或对服务器可暴露工具数量有硬性限制的客户端。

动态端点通过 execute 让你访问相同的托管操作。标准端点和本地 stdio 服务器保留各自的独立工具，不会列出 search 或 execute。

你无需安装二进制文件或创建令牌。连接只需两步，两步都是必需的：

添加服务器：将你选择的端点 URL 提供给客户端。
身份验证：通过浏览器登录，让客户端持有一个以你身份操作的令牌。

两个端点都要求身份验证。仅有 URL 的客户端在你登录之前会收到 401。部分客户端会在首次连接服务器时自动发起登录；另一些会将服务器标记为 "needs login" 并等待你点击。具体行为取决于你的客户端。

使用动态工具发现

如果客户端因工具过多而拒绝服务器，请连接到 https://mcp.bird.com/dynamic 并完成 OAuth 登录。客户端会列出两个工具：

search 按名称或描述关键词查找工具。每条匹配结果包含名称、描述、输入模式，以及标注该工具是读取还是修改数据的注解。
execute 使用指定参数调用一个已选工具。它可以读取数据、发送消息、修改记录或删除记录，具体取决于所选工具。

例如，你的代理可以通过以下工具调用找到工作区工具：

代码示例

{
  "name": "search",
  "arguments": { "query": "workspace_get", "limit": 3 }
}

读取返回的输入模式后，代理通过 execute 调用该工具：

代码示例

{
  "name": "execute",
  "arguments": { "tool": "workspace_get", "arguments": {} }
}

结果包含你当前的工作区。你还可以使用任务关键词进行搜索，例如 send email。搜索默认返回五条匹配结果，limit 接受 1 到 10 的值，查询最多 500 个字符。如果结果包含 has_more: true，请缩小查询范围以找到更相关的匹配。

搜索结果不会将工具添加到客户端的目录中。结果或恢复指引中提到的工具名称也需通过 execute 调用。执行使用你现有的权限；如果操作需要更多权限，客户端可能会请求你授权。找到工具并不意味着获得了访问权限。

动态执行会为原本显示小组件的工具返回数据。如需交互式 MCP Apps 小组件，请使用标准端点。客户端只看到一个执行工具，因此逐工具审批设置整体应用于 execute；在批准调用前请检查所选操作。该端点执行工具调用，不运行 JavaScript 或其他提供的代码。

连接客户端

以下示例使用标准端点。如需动态发现，将 https://mcp.bird.com/dynamic 替换为服务器 URL，并按相同的登录步骤操作。

Claude Code

添加服务器：

代码示例

claude mcp add --transport http bird https://mcp.bird.com

claude mcp list 现在将 bird 报告为 ! Needs authentication。Claude Code 不会自动打开浏览器，因此需要在会话内登录：

运行 /mcp。
选择 bird 并按 Enter。
选择 Authenticate。浏览器打开 Bird 的授权确认页面，在那里批准。

服务器随即显示为已连接，工具可以使用。无界面运行（claude -p）没有 /mcp 面板，因此请先在 shell 中通过 claude mcp login bird 进行身份验证。之后如需重新登录，/mcp 提供 Re-authenticate；Clear authentication 会删除已存储的令牌。

安装 bird-ai 插件会自动为你声明此服务器，替代 claude mcp add 命令。仍需进行身份验证，因为插件可以携带服务器但无法签发授权。安装后选择 /mcp > bird > Authenticate。

Cursor

在 ~/.cursor/mcp.json 中：

代码示例

{
  "mcpServers": {
    "bird": {
      "url": "https://mcp.bird.com"
    }
  }
}

然后在 Cursor 侧边栏中打开 Customize，选择 MCPs。找到 bird，按照登录提示操作，在浏览器中批准 Bird 的授权同意页面，然后返回 Cursor。

OpenCode

Bird 的 OpenCode 插件会为你注册服务器，同时包含 Bird 的 agent skills：

代码示例

opencode plugin github:messagebird/bird-ai --global

OpenCode 会将每个 MCP 工具添加到模型的上下文中，因此插件连接的是动态端点。当 OpenCode 的实验性代码模式开启时（OPENCODE_EXPERIMENTAL_CODE_MODE=1 或 OPENCODE_EXPERIMENTAL=1），OpenCode 会将 MCP 工具放在自身的搜索之后，此时插件改为连接 https://mcp.bird.com 的完整工具目录。

如果不使用插件而手动添加服务器，请在 opencode.json 中添加以下内容，可以放在项目目录或 ~/.config/opencode/opencode.json 中：

代码示例

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "bird": {
      "type": "remote",
      "url": "https://mcp.bird.com/dynamic"
    }
  },
  "permission": {
    "bird_execute": "ask"
  }
}

然后登录，浏览器会打开 Bird 的授权同意页面：

代码示例

opencode mcp auth bird

重启 OpenCode 以加载插件。授权通过后，opencode mcp list 会将 bird 显示为已连接。与上面的 permission 条目一样，插件会让 OpenCode 在每次 execute 调用前征求确认，因为运行的工具可能会更改你的工作区。

VS Code

在项目的 .vscode/mcp.json 中：

代码示例

{
  "servers": {
    "bird": {
      "type": "http",
      "url": "https://mcp.bird.com"
    }
  }
}

使用 settings.json？将相同的 bird 条目放在 mcp.servers 下。VS Code 会将其移入你的用户 mcp.json，可通过 MCP: Open User Configuration 打开：

代码示例

{
  "mcp": {
    "servers": {
      "bird": {
        "type": "http",
        "url": "https://mcp.bird.com"
      }
    }
  }
}

VS Code 在首次启动服务器时会要求你信任该服务器，然后自行运行 OAuth 流程：在它打开的浏览器窗口中批准 Bird 的授权同意页面。如果没有弹出窗口，请通过 MCP: List Servers 命令启动或重启 bird，然后在那里批准。生成的授权记录列在 Accounts > Manage Trusted MCP Servers 下，撤销 VS Code 的访问权限也在此处操作。

ChatGPT 和 Codex

在 ChatGPT 或 Codex 中安装 Bird，登录你的 Bird 工作区，然后让你的代理发送消息、管理域名和号码，以及检查投递状态。

如果要手动配置 Codex，请在 ~/.codex/config.toml 中添加以下条目：

代码示例

[mcp_servers.bird]
url = "https://mcp.bird.com"

然后从你的终端登录，这会打开浏览器：

代码示例

codex mcp login bird

Claude

Bird 已收录在 Claude 的连接器目录中。打开目录中的 Bird，点击 Connect to Claude 完成登录并批准授权同意页面。在每次对话中通过 + > Connectors 启用该连接器。此方式在 Claude 网页版和桌面应用中均可使用。

如需手动添加，请打开 Customize > Connectors，点击 +，然后选择 Add custom connector。粘贴 https://mcp.bird.com 并点击 Add。接着在 Bird 连接器上点击 Connect 完成登录并批准授权同意页面。在 Team 和 Enterprise 方案中，管理员通过 Organization settings > Connectors 添加一次连接器，每位成员仍需在 Customize > Connectors 下点击 Connect 获取自己的授权。在每次对话中通过 + > Connectors 启用该连接器。

如果要手动配置 ChatGPT，请按照 OpenAI 的 MCP 应用配置指南操作，将 https://mcp.bird.com 作为服务器 URL，将 OAuth 作为身份验证方式。完成 Bird 的浏览器登录，然后在聊天中使用 Bird。

Muse

Muse 将 Bird 作为自定义连接器添加。在 Muse 聊天中，让它设置一个：

代码示例

Set up a custom connector to the Bird MCP server at https://mcp.bird.com following https://bird.com/docs/ai/mcp-server.md so you can work with my Bird workspace.

Muse 会回复一个本次会话的连接链接。打开该链接并在浏览器中批准 Bird 的授权同意页面。该链接仅对你有效，且随会话过期。如果链接失效，请让 Muse 生成一个新的。

Factory Droid

代码示例

droid mcp add bird https://mcp.bird.com --type http

然后在 droid 中运行 /mcp，并从服务器管理器完成浏览器登录。

Antigravity

Bird 的 Antigravity 插件会为你注册服务器，同时包含 Bird 的 agent skills：

代码示例

curl -fsSL https://raw.githubusercontent.com/messagebird/bird-ai/main/antigravity.sh | bash

如果不使用插件而手动添加服务器，请在 ~/.gemini/config/mcp_config.json 中添加以下内容，或在 .agents/mcp_config.json 中为单个项目添加。Antigravity 从 serverUrl 读取远程服务器地址，因此请保留该键名：

代码示例

{
  "mcpServers": {
    "bird": {
      "serverUrl": "https://mcp.bird.com"
    }
  }
}

然后登录：打开侧边栏中的 Customizations（在 IDE 中，macOS 使用 Cmd+,、Windows 和 Linux 使用 Ctrl+, 打开 Agent settings），在 bird 旁边选择 Authenticate。如果 bird 未列出，请重启 Antigravity。在浏览器中批准 Bird 的授权同意页面，复制其显示的授权码，粘贴到 Antigravity 中，然后选择 Submit。

Agent Plugins

bird-ai 插件在一个遵循 Agent Plugins 规范的 mcp.json 中声明了此服务器。实现了该规范的宿主在插件安装时会读取该文件，因此无需手动编写服务器配置：安装插件并登录即可。

任何其他宿主

找到用于添加 remote、HTTP 或 custom MCP 服务器的设置，通常在 Connectors 或 Integrations 菜单下，然后填入 URL。字段位置因客户端而异；使用你选择的托管端点 URL。接着找到该客户端的登录入口：服务器旁边的 Connect、Authorize 或 Needs login 控件、login 子命令，或客户端自动打开的浏览器窗口。如果客户端列出了 Bird 的工具但每次调用都失败，说明它有 URL 但仍需要授权。

登录时会发生什么

浏览器会打开 Bird 授权同意页面。登录后，选择授予工作区还是组织权限，并选择要委托哪些权限。由于 MCP 客户端是自行注册的，客户端名称为自行声明，因此页面会将其标记为未经 Bird 验证。在批准之前，请确认它确实是你启动的客户端。之后工具会出现在代理的列表中，令牌会静默刷新，因此每个客户端只需操作一次。

验证连接是否成功的最快方式是让代理调用 whoami：它会返回已登录用户，因此得到真实响应即表示授权已生效。在动态端点上，通过 execute 调用它，使用 tool: "whoami" 和空的 arguments。

授权范围取客户端请求的权限、你批准的权限和你实际持有的权限三者的交集；org:owner 和 platform-admin 作用域不可委托。授权会出现在你个人资料的已连接应用列表中，在那里撤销会立即断开客户端的访问。

握手流程

连接客户端不需要了解这些内容。只有在调试无法完成身份验证的客户端或自行编写客户端时才需要。

托管层使用 Streamable HTTP，且无需凭据：它不存储密钥，也不自行进行任何验证。每个请求携带你自己的 OAuth bearer token，由 Bird 的 API 逐请求验证。服务器是无状态的，区域流量自动路由，因此同一个 URL 在任何地方都可用。

登录流程使用标准 MCP。客户端的区别仅在于触发方式：首次工具调用或选择 Authenticate。流程启动后，身份验证步骤无需额外配置：

客户端发出未经身份验证的请求，收到 401 响应，其中 WWW-Authenticate 请求头指向 Bird 的 RFC 9728 受保护资源元数据（/.well-known/oauth-protected-resource）。
客户端从中发现授权服务器，然后动态注册自身（RFC 7591）。动态注册免去了预共享 client ID 或手动配置的需要。
浏览器打开 Bird 的授权同意页面。
客户端用结果换取访问令牌（PKCE；自动刷新），Bird 工具随即出现。

本地模式：通过 stdio 使用 CLI 运行

在 bird CLI 内运行本地 MCP 服务器，适用于支持 shell 的代理或需要访问本机文件的场景。安装 CLI，运行一次 bird auth login，然后将客户端指向 bird mcp 命令。

你不需要自己运行 bird mcp：你的客户端会启动它并通过 stdin/stdout 与之通信。每个客户端只需要两个信息：命令（bird）和参数（mcp）。此方式无需逐客户端登录，因为 bird auth login 已经持有授权。

Cursor

代码示例

{
  "mcpServers": {
    "bird": {
      "command": "bird",
      "args": ["mcp"]
    }
  }
}

VS Code

在项目的 .vscode/mcp.json 中：

代码示例

{
  "servers": {
    "bird": {
      "type": "stdio",
      "command": "bird",
      "args": ["mcp"]
    }
  }
}

Claude Code

代码示例

claude mcp add bird -- bird mcp

本地服务器如何进行身份验证

本地服务器以你的身份运行，复用 CLI 存储的登录凭据。bird auth login 会打开浏览器发起 OAuth 流程，你在其中授予工作区权限的一个子集。签发的令牌受托管授权的权限上限约束。org:owner 和 platform-admin 作用域均不可用。bird mcp 从 CLI 凭据文件中读取并刷新存储的登录信息，该文件权限模式为 0600。与托管层一样，你的客户端配置中没有 BIRD_API_KEY 或其他密钥。如果登录信息缺失，bird mcp 会拒绝启动，并提示你运行 bird auth login。

你不会暴露任何监听器：服务器在你的机器上运行，位于客户端的沙箱内，仅在客户端需要时存在。API 主机会自动跟随你登录所在的区域；--base-url（或 BIRD_API_URL）可将其覆盖为非生产环境以便测试。

工具涵盖的范围

工具集覆盖 Bird 支持的每个渠道，以及围绕这些渠道的账户和配置任务。它是经过筛选的，而非完整的 API 接口：每个工具都限定在代理实际执行的任务范围内，破坏性操作会加注标记，以便宿主在执行前征求确认。

Email 拥有最多的工具，因为它需要配置的内容最多。其他渠道采用相同的发送和查看模式。

消息发送

发送和查看 email：email_send、email_send_batch、email_list 和 email_get，后者返回消息及其汇总投递状态。每个收件人的投递状态和事件日志需要单独的工具调用。
发送和查看 SMS：sms_send、sms_send_batch、sms_get、sms_list 和 sms_list_events，与 email 的模式一致。sms_templates_list 和 sms_templates_get 用于读取模板目录。
发送和查看 WhatsApp：whatsapp_send、whatsapp_get、whatsapp_list、whatsapp_list_events 和 whatsapp_media。模板在 whatsapp_templates_* 下提供完整的编辑功能，包括按版本和按语言的内容管理。
查看语音通话分段：voice_legs_get 和 voice_legs_list 读取通话分段，voice_stats_* 下提供按国家和按响应码的统计数据。voice_session_credentials_create 创建工作区凭据，供 SIP 或软电话客户端用于身份验证。
验证收件人：verify_verifications_create 发送一次性验证码，verify_verifications_check 验证收件人提交的内容，verify_verifications_next_channel 回退到其他渠道。
创建语音通话（预览）：voice_calls_create 使用已启用、未归档序列的活跃发布版本来准备外呼。需要人工在浏览器中审核并执行该请求；准备操作不会拨出电话。权限和重试说明请参阅创建语音通话。本地 bird mcp 服务器需要包含此工具的 CLI 版本。

准备渠道以发送消息

设置发送域：email_domains_create 添加发送域并返回需要发布的 DNS 记录；email_domains_verify 重新检查这些记录；另有 email_domains_list 和 email_domains_get。
认领并注册 SMS 发送者：sms_senders_create 认领发送者，sms_senders_requirements 报告相应国家对其的要求，sms_senders_registrations_create 完成注册。美国 A2P 流量通过 sms_10dlc_* 的品牌、活动和提交工具处理。
配置号码：numbers_available_list 搜索号码，numbers_orders_create 购买号码，numbers_cancel 在付费周期结束时退回号码（如果号码没有订阅则立即退回），numbers_release 立即退回号码。whatsapp_numbers_precheck 在你下单前报告 WhatsApp 是否会接受该号码。
检查账户是否可以发送：trust_* 工具报告购买号码或注册发送者所需满足的组织级要求。

邮件送达能力

编写邮件模板：email_templates_create、email_templates_list、email_templates_get、email_templates_update、email_templates_duplicate 和 email_templates_preview（使用示例值渲染草稿而不实际发送）。版本位于 email_templates_versions_* 下，其中 email_templates_versions_submit 冻结草稿并将其设为发送所使用的版本，email_templates_versions_languages_* 编辑草稿的各语言内容。代理编写的内容在提交之前不会发送给收件人。
管理屏蔽列表：email_suppressions_list、email_suppressions_check（该地址是否可以安全发送？）、email_suppressions_add 和 email_suppressions_remove（标记为破坏性操作，因为无理由地移除屏蔽会损害发送者信誉）。
管理专用 IP 和 IP 池：email_dedicated_ips_create、email_dedicated_ips_list、email_dedicated_ips_get、email_dedicated_ips_assign（将 IP 移入池中）和 email_dedicated_ips_delete；另有 email_ip_pools_create、email_ip_pools_list、email_ip_pools_get、email_ip_pools_update 和 email_ip_pools_delete，用于管理发送所经由的 IP 池。

受众与配置

管理联系人和受众：contacts_* 和 contact_properties_* 用于管理发送对象，audiences_* 用于管理发送列表，preferences_* 用于管理同意授权和退订。
配置 Realtime：realtime_apps_* 和 realtime_apps_keys_* 创建 Realtime 客户端连接所需的应用和密钥。
查询某人信息：lookup_phone_number 和 lookup_email 报告 Bird 在你发送之前对某个地址已知的信息。
查看配置：webhooks_list、workspace_get 和 whoami（当前登录用户的 id、邮箱、名称）。

你的客户端会显示实时工具列表，包含名称、描述和输入模式。以该列表为权威清单。一个适合端到端试跑的入门任务：

Call whoami to find my email, then send me a test email from onboarding@messagebird.dev and tell me when it's delivered.

MCP 还是 CLI？

相同的功能面、相同的认证模型，但调用方不同。对于支持 shell 的代理（Claude Code、Cursor 终端、CI），CLI 更轻量：JSON 输出、语义化退出码，每次操作消耗的 token 也少得多。MCP 面向通过调用工具而非运行 shell 的宿主，托管端点还能触达那些完全无法执行二进制文件的客户端（Claude Desktop、ChatGPT、移动端）。你不必事先选定：托管 URL 无需安装，而一旦装好 CLI，本地 bird mcp 也已就绪。

后续步骤

MCP Events：为你的客户端订阅 Bird 事件（例如邮箱中的新邮件），并以签名 webhook 的形式接收每个事件。
用 AI 查询邮件分析数据：用自然语言询问投递、互动和延迟相关信息。
AI 入门引导：本页的快速入门版本，以及机器可读的文档语料库。
Agent skills：bird-ai 市场插件，skills 加上此 MCP 服务器，一步安装。
面向代理的 CLI：无需 MCP，从支持 shell 的代理驱动 Bird：JSON 输出、语义化退出码、OAuth 登录。
身份验证：API 密钥、区域以及请求的授权方式。

继续查看此主题的文档、指南和示例。

获取实施简报

相关资源