threads-mcp

一个用于 Threads API 的 MCP 服务器。它只做平台 I/O，不做其他任何事情：发布帖子、读取你自己的帖子、读取它们的洞察数据、检查发布配额。没有编辑逻辑，没有调度，对你应该写什么没有任何意见。

它是代理（agent）为了触达 Threads 所需要的那一块拼图。要发什么是你的问题。

npx -y @andreaselmi/threads-mcp    # needs THREADS_ACCESS_TOKEN in the environment

• 快速开始

• 工具

• 获取访问令牌

• 将它接入客户端

• 故障排除

• 它刻意不做的事

• 开发

快速开始

要求 Node 20 或更高版本。你不需要安装任何东西：MCP 客户端通过 npx 运行服务器，首次使用时它会获取该服务器。

1. 获取一个长期访问令牌——下面有完整指南。这是唯一真正麻烦的部分，而且这是 Meta 的错，不是这个包的错。

2. 在你启动 MCP 客户端的 shell 中导出它：

   export THREADS_ACCESS_TOKEN="THQ..."

3. 将服务器添加到客户端的 MCP 配置中：

   {
     "mcpServers": {
       "threads": {
         "command": "npx",
         "args": ["-y", "@andreaselmi/threads-mcp"]
       }
     }
   }

4. 重启客户端并问它你是谁。它应该调用 threads_whoami 并用你的用户名来回答。

要在完全不涉及客户端的情况下检查服务器是否正常：

printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  | npx -y @andreaselmi/threads-mcp

一行包含 threads-mcp 的 JSON 表示它已启动并读取了你的令牌。stderr 上的错误消息会告诉你缺了什么。

Related MCP server: threads-growth-mcp

工具

这两个发布工具被标记为 destructiveHint: true；其余都是 readOnlyHint。那些会在破坏性工具前要求确认的客户端也会在这些工具前要求确认，而且应该如此：发布的帖子会立即上线，API 无法编辑或删除它。 要删除一条帖子，只能打开 Threads 应用。

threads_post_insights 只读取你自己帖子的洞察数据，并且需要 threads_manage_insights 权限范围。threads_publishing_limit 报告滚动 24 小时配额，默认每个账户 250 条帖子。

为什么存在 threads_publish_container

在 Threads 上发布需要两次调用：先创建容器，再发布它。如果第二次调用失败，容器仍然存在并在 24 小时内有效——重试整个操作会重复发布相同的文本。当发布失败时，此服务器会把容器 id 放进错误消息中；将它传给 threads_publish_container 即可恰好完成一次发布。

服务器还会在发布容器之前等待它达到 FINISHED 状态，每 2 秒轮询一次，最长持续一分钟，这样慢的容器不会被误认为是失败。

获取访问令牌

Meta 的流程有四个步骤，没有捷径。第一次请预留十五分钟。

1. 创建应用

前往 developers.facebook.com/apps，创建一个带有 Threads 用例的应用。仪表盘会生成两组凭据——请使用 Threads 专用的应用 ID 和密钥，而不是 Facebook 的那组。这一步几乎让所有人都栽跟头。

2. 添加权限范围和测试者

在 Threads 用例下，添加你需要的权限范围：

然后把你的 Threads 账户添加为测试者，并从该账户的设置中接受邀请（账户 → 网站权限 → 邀请）。在邀请被接受之前，每次调用都会以权限错误失败，而且错误信息中从不提及邀请。

3. 获取短期令牌

在浏览器中打开授权窗口，替换其中的占位符：

https://threads.net/oauth/authorize
  ?client_id=YOUR_APP_ID
  &redirect_uri=YOUR_REDIRECT_URI
  &scope=threads_basic,threads_content_publish,threads_manage_insights
  &response_type=code

批准后，你会到达你的 redirect_uri，并带有追加的 ?code=...。重定向 URI 必须与应用设置中注册的某个 URI 完全匹配。复制该 code——它是单次使用的，并且几分钟内过期——然后兑换它：

curl -X POST https://graph.threads.net/oauth/access_token \
  -F client_id=YOUR_APP_ID \
  -F client_secret=YOUR_APP_SECRET \
  -F grant_type=authorization_code \
  -F redirect_uri=YOUR_REDIRECT_URI \
  -F code=THE_CODE_FROM_THE_REDIRECT

这会返回一个短期令牌，有效期为一小时。不要停在这里。

4. 将它兑换为长期令牌

curl -G https://graph.threads.net/access_token \
  -d grant_type=th_exchange_token \
  -d client_secret=YOUR_APP_SECRET \
  -d access_token=THE_SHORT_LIVED_TOKEN

结果的有效期为60 天。这就是 THREADS_ACCESS_TOKEN 的值。

保持长期令牌有效

长期令牌在创建至少 24 小时后、过期之前可以刷新。每次刷新都会再给 60 天：

curl -G https://graph.threads.net/refresh_access_token \
  -d grant_type=th_refresh_token \
  -d access_token=YOUR_LONG_LIVED_TOKEN

一个 60 天未使用的令牌会过期且无法刷新——你要从第 3 步重新开始。在日历里设个提醒；没有任何东西会警告你。

将它接入客户端

环境变量

令牌在启动时从环境中读取，绝不会写入任何地方——不会写入文件，也不会写入日志行。相比把它写进配置文件，更推荐在你的 shell 中导出它：配置文件会被提交到版本库，shell 导出不会。

Claude Code

claude mcp add threads --scope user -- npx -y @andreaselmi/threads-mcp

或者在一个项目的根目录提交一个 .mcp.json，这样任何处理该项目的人都能获得该服务器：

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp@^0.1.0"]
    }
  }
}

固定 ^0.1.0 会获取修复，但不会获取未来会改变工具的大版本。用 /mcp 检查连接。

Claude Desktop、Cursor 和其他客户端

同样的形式，位于该客户端的配置文件中——Claude Desktop 使用 claude_desktop_config.json，Cursor 使用 ~/.cursor/mcp.json。不继承你的 shell 环境的客户端需要显式传入令牌：

{
  "mcpServers": {
    "threads": {
      "command": "npx",
      "args": ["-y", "@andreaselmi/threads-mcp"],
      "env": { "THREADS_ACCESS_TOKEN": "THQ..." }
    }
  }
}

如果你这样做，该文件现在就包含一个有效凭据：请将它排除在版本控制之外。

改为安装它

如果你不想每次启动都走 npx：

npm install -g @andreaselmi/threads-mcp

然后使用没有 args 的 "command": "threads-mcp"。

故障排除

服务器无法启动 / 客户端显示 CONNECTION_CLOSED。 进程在启动时退出，几乎总是因为客户端启动时所处的环境中没有设置 THREADS_ACCESS_TOKEN。在终端里导出它不会传递到一个已经在运行的应用，也不会传递到从 Dock 启动的应用。手动运行服务器以查看真实的错误消息：

npx -y @andreaselmi/threads-mcp

它会打印原因并退出。

Invalid OAuth access token 或类似错误。 令牌已过期（60 天），或者你仍在使用第 3 步的短期令牌。重做第 4 步。

某个本应有效的调用出现了权限错误。 要么权限范围缺失——洞察和发布各自需要各自的权限范围——要么从未在 Threads 账户的设置中接受测试者邀请。

Post is N characters, the Threads limit is 500。 这个错误由本服务器在任何请求发送之前抛出，因此没有发布任何内容。请拆分文本。

发布失败了，但你不确定它是否发出去了。 阅读错误：如果它提到了一个容器 id，说明容器存在，帖子没有发出去。请使用该 id 调用 threads_publish_container，而不是再次发布。如果错误中没有提到容器 id，请在重试之前检查 threads_list_posts。

配额已用完。 threads_publishing_limit 显示的是滚动 24 小时窗口——每个账户 250 条帖子。当配额用完时，在帖子从窗口中过期之前，无法发布任何内容。

它刻意不做的事

仅支持文本帖子——不支持图片、视频、轮播或链接附件。它读取你自己的帖子，而不是回复、提及或任何其他人的内容。它不调度、不按定时器重试，也不在调用之间保持状态：它不持有数据库，也不记忆任何东西。

它对你发布什么也一无所知。这里没有主题，没有语气，没有编辑规则；这些属于调用它的任何一方。添加产品特定行为的拉取请求会被要求将这些行为移到调用方。

开发

npm install
npm test          # vitest, no network: fetch is stubbed
npm run dev       # run the server from source over stdio
npm run build     # tsc to dist/

每个测试都针对一个假的 fetch 运行，因此测试套件永远不会接触真实的 API，也不需要令牌。问题和拉取请求：github.com/andreaselmi/threads-mcp。

许可证

MIT