奇 奇连 AI
学习路线图课程工具计算器企业服务关于加入会员

Macro 的 MCP 服务能做什么：一个远程端点、OAuth 登录，和注册表里的 16 个工具

2026-08-17

想让本地的 AI 客户端去读写 Macro 里的邮件、文档、任务，第一步不是研究哪个工具怎么调，而是先把连接这件事搞清楚。Macro 官方给的东西比很多人预想的要少——就一个 URL，加上三段客户端配置。少不等于简单，因为”少”意味着大量你关心的问题，文档里根本没写答案，你得知道哪些是它明确说了的、哪些是它没说的。

这篇是 Macro MCP 这条线的入口。目标是把四件事讲透：这个服务的形态是什么（远程还是本地）、三类客户端各自怎么接、鉴权怎么走、工具注册表里都有些什么。具体某个工具的参数、返回结构、怎么用，那是后面几篇的事，这里不展开。

先说一句会影响你整体判断的：Macro 的 MCP 文档页标题就叫 MCP Setup，描述是”把 AI 客户端连到 Macro MCP 服务器”。它的定位很清楚，是接入说明，不是能力说明。所以你在这页上找不到配额、找不到作用域粒度、也找不到哪个工具需要什么权限——想清楚这一点，能省下不少来回翻文档的时间。

端点只有一个，而且是远程的

官方给出的 MCP 端点是：

https://mcp-server.macro.com/mcp

文档对这个端点补了两句关键说明：服务器是远程的（remote），不需要本地进程；鉴权在客户端连接时通过 Macro 的 OAuth 流程完成。

“不需要本地进程”这句值得单独拎出来。MCP 生态里有相当一部分服务是 stdio 形态的，你得先在机器上装个包、配好可执行路径、让客户端把它当子进程拉起来，随之而来的是 Node 版本、路径转义、环境变量继承一堆麻烦。Macro 走的是另一条路——HTTP 传输的远程服务器，你的客户端只要能发 HTTP 请求并完成浏览器登录就行，机器上不落任何东西。

这带来的直接后果是：排查方向变了。连不上的时候，不用去查”本地那个进程有没有起来""路径对不对”，问题基本只会出在三个地方——网络能不能到这个域名、客户端的 transport 类型配没配成 http、OAuth 那一步有没有真正走完。这三类具体怎么定位，我单独写在了 MCP 连不上时的排查路径 里。

三种接法，命令按原文抄

文档给了三种客户端的接入方式，命令我按原文列出来，不要凭印象改参数名。

Claude Code：

claude mcp add --transport http macro https://mcp-server.macro.com/mcp

加完之后，启动 Claude Code，使用名为 macro 的 MCP 服务器，在提示出现时完成浏览器登录流程。

Codex CLI：

codex mcp add macro --url https://mcp-server.macro.com/mcp

同样是启动 Codex CLI、调用 macro 这个 MCP 服务器，然后在浏览器里完成 OAuth 登录。

对于接受 JSON 形式 MCP 配置的编辑器，文档给的是往 mcpServers 下面加这么一段：

{
  "macro": {
    "type": "http",
    "url": "https://mcp-server.macro.com/mcp"
  }
}

配好以后从编辑器里触发一次连接，再去浏览器把登录流程走完。

三种方式放一起对照，差别其实只在语法：

客户端声明传输方式的写法服务器名登录时机
Claude Code--transport httpmacro使用该服务器时按提示登录
Codex CLI--url（未出现显式 transport 参数）macro调用该服务器时走 OAuth
IDE / JSON"type": "http"macro从编辑器触发连接后登录

三种写法都把服务器命名成了 macro。这个名字不是协议规定的，是文档里的约定——但建议跟着用，因为后续文档、你自己的提示词、团队里别人的配置，默认都是这个名字。改成别的不会出错，只是每次沟通都要多解释一句。

鉴权：OAuth，浏览器里完成

文档对鉴权只有一句定性描述：认证在客户端连接时通过 Macro 的 OAuth 流程完成。三种接法的说明里也都重复了同一件事——启动客户端、触发连接、在浏览器完成登录。

所以流程是标准的：客户端发起连接 → 拉起浏览器 → 你在 Macro 那边确认 → 授权信息回到客户端 → 后续调用带着凭据走。你不需要手工去生成 API key，也不需要往配置文件里塞任何密钥——上面三段配置里，你能看到的字段就是 URL 和类型，没有任何存放令牌的位置。

这一点对配置管理是好事：MCP 配置文件里不含机密，可以放心提交到仓库、在团队里共享，每个人接上之后各自登录各自的账号，拿到的自然是各自的数据视野。

至于授权之后你到底能碰到哪些数据，官方这页 MCP 文档没有展开。它没有列出作用域清单，没有说明能不能只授只读权限，也没有说明当你在一个团队工作区里时，MCP 通道看到的范围和你在 Macro 界面里看到的范围是不是完全一致。合理的推断方向是它沿用账号本身的权限，但这是推断，不是文档写明的事实。要判断边界，得回到 Macro 的权限模型那套规则去看，而不是指望 MCP 这页给答案。

门槛：所有套餐都能用，包括 Free

文档里有一句容易被划过去但很重要的话：MCP 访问在 Macro 的每个套餐上都可用，包括 Free。

这意味着接入这件事本身不构成付费门槛，你可以先用免费账号把链路跑通、把工具试一遍，再决定要不要把工作流搬过来。需要注意的是这句话管的是”MCP 通道能不能用”，至于免费套餐在别的维度上有什么限制、调用有没有频率上限，这页文档没有说明。

工具注册表里有 16 个工具

工具参考页写明了一件事：这些页面是从 Macro 的 Rust MCP 工具注册表生成的。也就是说，工具列表不是人工维护的一篇文档，而是代码里的注册表导出来的——列表和实际能调到的工具，理论上是同步的。

注册表里列出的 16 个工具是：bash_code_execution、ContentSearch、CreateDocument、GetEntityProperties、GetThread、ListEntities、NameSearch、ReadContent、ReadMetadata、ReadThread、SendEmail、SetEntityProperty、text_editor_code_execution、UpdateThreadLabels、web_fetch、web_search。

官方的这份清单是按字母排的，没有分组。下面这个归类是我按工具名做的整理，方便你建立心智模型，不是官方分类：

归类工具大致解决什么
实体属性ListEntities、GetEntityProperties、SetEntityProperty列出对象、读它的结构化字段、改字段
搜索ContentSearch、NameSearch按内容找、按名称找
内容读写ReadContent、ReadMetadata、CreateDocument读正文、读元数据、建文档
会话与邮件GetThread、ReadThread、SendEmail、UpdateThreadLabels取会话、读会话、发信、改标签
代码执行bash_code_execution、text_editor_code_execution执行类能力
联网web_fetch、web_search抓网页、搜网页

有个细节值得留意：命名风格是两套。ContentSearch、SendEmail 这类是大驼峰，bash_code_execution、web_search、text_editor_code_execution 这类是下划线小写。两套风格并存，通常意味着它们的来源不同——一批是 Macro 自己注册的业务工具，另一批更像是通用能力。文档没有解释这个差异，我也不替它解释，但在你写提示词、拼工具名的时候，这个区别会实实在在地咬你一口：工具名大小写写错，客户端是不会帮你纠正的。

从归类表也能看出这套工具的重心在哪。前四类共 12 个工具，全部围绕 Macro 自己的数据——实体、属性、内容、会话。这跟 Macro 把邮件、文档、任务放在同一套数据结构里的做法是一致的：MCP 通道暴露出来的不是”邮件 API + 文档 API + 任务 API”三套接口，而是一层更抽象的实体和内容操作。这也是为什么 ListEntities 和 GetEntityProperties 这种听起来很抽象的工具会排在前面——它们是通用入口。

具体到每一类怎么用，我拆成了几篇分别写：实体类工具讲列实体、取属性、改属性这条线；搜索类工具讲内容搜索和名称搜索的区别与配合。

这页文档没回答的几个问题

接入前把预期摆正，比接完了再失望强。以下这些，官方 MCP 页面确实没有给答案：

第一，没有速率限制和配额说明。文档说所有套餐都能用 MCP，但没有说不同套餐在调用量上有没有差别。

第二，没有作用域和最小权限。你无法从这页文档判断能否只授予只读权限，或者把某些工具排除在授权之外。

第三，没有自托管场景下的 MCP 说明。这页给的端点是 mcp-server.macro.com 这个托管域名，本地跑起来的 Macro 要怎么对接 MCP，不在这页的讨论范围内。

第四，没有错误码和排障清单。连接失败会返回什么、OAuth 中断了怎么重来，都得靠客户端自己的日志去判断。

第五，除了上面三种客户端，其它 MCP 客户端能不能接、有没有已知不兼容，文档没有提。从配置形态看，只要客户端支持 HTTP 传输的远程 MCP 服务器和 OAuth 授权，理论上都能接——但这是从配置结构推出来的，官方没有背书。

所以这篇的实用结论其实很短：Macro 的 MCP 是一个远程 HTTP 端点，配置里不放密钥，登录走浏览器 OAuth，免费账号就能试，能调的是注册表里那 16 个工具。剩下的边界问题，官方文档在这页停住了，你得靠实际连上去以后自己摸。

延伸阅读

本文依据 Macro 官方仓库（github.com/macro-inc/macro，AGPL-3.0 协议）的 apps/docs/ 产品文档、 MCP 工具参考与自托管说明整理，核对日 2026-08-17。 我们没有注册或运行过 Macro，因此不涉及界面外观与操作手感； 官方标注为计划中的能力文中已如实标明，不代表当前可用。 价格与额度以官网 macro.com 最新页面为准；许可证相关问题请咨询专业人士并以官方许可证原文为准。

想系统学会用 AI？报名体系课或加入会员，照着学、照着用。

浏览课程 加入会员