Threads MCP 服务器

threads-mcp 是一个用于官方 Threads API 的 stdio MCP 服务器。它旨在紧跟已发布的 Meta Threads 文档，同时为身份验证、发布、读取、审核、洞察、发现、位置和设置诊断提供实用的 MCP 工具接口。

当前版本特意限制在官方记录的 Threads 功能和官方 Postman 集合范围内。它不依赖于难以在公共包中维护的未记录回退端点或便捷包装器。

亮点

• 仅限官方 Threads API 范围

• 用于身份验证、个人资料查找、发布、读取、回复、洞察、搜索、位置、oEmbed 和诊断的 MCP 工具

• 发布输入采用 camelCase 建模，并在内部序列化为 Threads 预期的 snake_case 参数

• 支持多步骤轮播图发布

• 用于重试、轮询、分页和标准化 Meta API 错误的共享客户端层

快速入门

1. 安装依赖：

npm install

2. 构建服务器：

npm run build

3. 创建本地环境文件并至少设置 THREADS_ACCESS_TOKEN。

4. 如果您仍需要令牌，请运行本地 OAuth 助手：

npm run auth:token

5. 启动服务器：

node dist/index.js

6. 在对真实账户使用发布或审核流程之前，请调用 validate_setup。

工具目录

身份验证

• exchange_code_for_token

• get_long_lived_access_token

• refresh_access_token

• get_app_access_token

个人资料与发现

• get_me

• get_profile

• get_profile_threads

发布与生命周期

• get_publishing_limit

• create_thread_container

• publish_thread

• create_and_publish_thread

• repost_thread

• delete_thread

读取与回复

• get_threads

• get_thread

• get_replies

• get_thread_conversation

• get_pending_replies

• manage_reply

• manage_pending_reply

洞察、搜索与嵌入

• get_user_insights

• get_thread_insights

• search_threads

• get_mentions

• get_oembed

位置与诊断

• search_locations

• get_location

• validate_setup

v1 明确排除的功能

• Webhooks

• 内置 OAuth 回调托管

• 官方文档或官方 Postman 集合未涵盖的任何未记录回退端点或便捷功能

架构

服务器分为几个清晰的层级：

• src/index.ts 引导 MCP stdio 传输。

• src/threads/client.ts 负责经过身份验证的 HTTP 调用、重试、分页、轮询和标准化 Meta API 错误。

• src/tools/ 包含每个工具系列的一个模块以及共享模式。

发布输入模型作为涵盖 text、image、video、carousel 和 reply 的单一公共可辨识联合类型公开。

先决条件

在服务器能够进行实时 API 调用之前，您需要具备以下所有条件：

• 为 Threads 用例配置的 Meta 应用

• 您要操作的账户的 Threads 用户访问令牌

• 集成需要时的高级访问权限和应用审核

• 服务器运行机器上安装 Node.js 20+

环境变量

大多数用户令牌工具所需：

• THREADS_ACCESS_TOKEN

可选：

• THREADS_APP_ID

• THREADS_APP_SECRET

• THREADS_REDIRECT_URI

• THREADS_API_BASE_URL

• THREADS_USER_ID

• THREADS_MAX_RETRIES

• THREADS_RETRY_BASE_DELAY_MS

• THREADS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_TIMEOUT_MS

• THREADS_PUBLISH_STATUS_POLL_INTERVAL_MS

复制 .env.example 并至少设置访问令牌。如果您不传递显式的应用访问令牌，则 THREADS_APP_ID 和 THREADS_APP_SECRET 对于身份验证助手工具和 get_oembed 也是必需的。

如何获取 THREADS_APP_ID

• 在 Meta for Developers 仪表板中打开您的应用：https://developers.facebook.com/apps/

• 打开使用 Threads 用例创建的应用

• 转到 Use Cases -> Threads -> Customize -> Settings

• 从该页面复制 Threads App ID

• 将该值用作 THREADS_APP_ID

重要提示：

• 不要使用顶级应用仪表板或设置页面中的通用 Meta 应用 ID

• 使用来自 Use Cases -> Threads -> Customize -> Settings 的 Threads 用例特定凭据

THREADS_APP_SECRET 来自同一个 Threads 用例设置页面。请保持私密。

令牌助手脚本

该存储库包含一个遵循 Meta Threads 访问令牌流程的本地 OAuth 助手：

1. 打开 Threads 授权窗口

2. 在本地回调 URL 上接收授权码

3. 将其交换为短期令牌

4. 将其交换为长期令牌

5. 将结果保存到 .env 中作为 THREADS_ACCESS_TOKEN

设置：

• 将您的 Meta 应用凭据添加到 .env

• 确保您应用的有效 OAuth 重定向 URI 与 THREADS_REDIRECT_URI 匹配

运行：

npm run auth:token

可选标志：

• --redirect-uri http://127.0.0.1:8788/callback

• --env-file .env.local

• --no-open

各工具系列所需的范围

• threads_basic 由 get_me、get_profile、get_threads、get_thread 和基准设置验证使用。

• threads_content_publish 由 get_publishing_limit、create_thread_container、publish_thread 和 create_and_publish_thread 使用。

• threads_read_replies 由 get_replies 和 validate_setup 中的安全回复读取探测使用。

• threads_manage_replies 由 manage_reply 使用。

• threads_manage_insights 由 get_user_insights 和 get_thread_insights 使用。

• threads_keyword_search 由 search_threads 使用。

• threads_profile_discovery 由 get_profile 和 get_profile_threads 用于公共账户发现场景。

• threads_location_tagging 由 search_locations、get_location 以及设置 locationId 的发布流程使用。

• threads_delete 由 delete_thread 使用。

validate_setup 执行安全探测以推断对 threads_basic、threads_content_publish、threads_read_replies、threads_manage_insights、threads_keyword_search、threads_profile_discovery 和 threads_location_tagging 的访问权限。它特意不对 threads_manage_replies 或 threads_delete 执行破坏性探测，因此这些范围不会被设置主动验证。

发布行为

服务器以 camelCase 对官方容器选项进行建模，并在内部将其序列化为 Threads API 预期的 snake_case 参数。

支持的输入包括：

• 通用字段：text、replyControl、replyToId、quotePostId、topicTag、locationId、textEntities、allowlistedCountryCodes

• 仅文本字段：linkAttachment、pollAttachment、textAttachment、gifAttachment、enableReplyApprovals、autoPublishText、isGhostPost

• 图像或视频字段：imageUrl、videoUrl、altText、isSpoilerMedia

• 轮播图项目：经过验证的图像或视频项目数组，具有每个项目的媒体字段

轮播图发布遵循官方的多步骤流程：

1. 为每个图像或视频创建一个项目容器，并设置 is_carousel_item=true

2. 创建父轮播图容器，并设置 children=[...]

3. 发布父容器

覆盖范围说明

该存储库目前涵盖以下官方 Threads API 系列：

• 身份验证助手

• 发布，包括引用帖子、转发发布和容器状态轮询

• 用户个人资料查找和公共个人资料帖子检索

• Threads 媒体检索

• 回复检索、扁平化对话、待处理回复、隐藏和取消隐藏，以及批准和忽略流程

• 用户和帖子洞察

• 关键词搜索和提及

• 位置搜索和位置检索

• oEmbed

• 设置诊断

本地 MCP 配置示例

Claude Desktop 风格配置示例：

{
  "mcpServers": {
    "threads": {
      "command": "node",
      "args": ["/absolute/path/to/threads-mcp/dist/index.js"],
      "env": {
        "THREADS_ACCESS_TOKEN": "thdt_your_user_access_token",
        "THREADS_APP_ID": "optional_app_id",
        "THREADS_APP_SECRET": "optional_app_secret"
      }
    }
  }
}

如果您稍后将此包发布为 CLI，则 command 可以变为 threads-mcp。

发布

包元数据已配置为作为公共包进行 npm 发布：

• 包名称：threads-mcp

• 当前版本：0.0.0

• CLI 入口点：threads-mcp

• 发布访问权限：public

发布前，请运行：

npm run build
npm test
npm publish --access public

prepublishOnly 配置为在 npm publish 期间自动运行构建和测试步骤。

开发

在 Node.js 可用后安装依赖：

npm install
npm run build
npm test

建议的手动检查：

1. 运行 npm run build 以验证 TypeScript 编译。

2. 运行 npm test 以执行模式、客户端和工具注册测试。

3. 使用 node dist/index.js 启动服务器。

4. 首先使用真实令牌调用 validate_setup。

5. 针对测试 Threads 账户练习 create_thread_container 和 publish_thread。

已知限制

• v1 中传输仅限 stdio

• 没有内置 OAuth 回调服务器；令牌交换助手作为 MCP 工具公开

• validate_setup 无法在不执行状态更改审核调用的情况下安全地验证 threads_manage_replies

• validate_setup 也不执行状态更改删除探测

• create_and_publish_thread 特意拒绝 autoPublishText=true，因为该标志与工具的显式两步契约冲突

• 回复发布被建模为由官方 reply_to_id 参数支持的专用 reply 变体，目前在公共模式中针对文本回复

• 实时 API 行为的验证仍取决于有效的应用凭据、已批准的范围和真实的 Threads 账户

用于 API 范围和端点选择的来源

• Meta Threads API 参考：https://developers.facebook.com/docs/threads/reference

• Meta Threads 发布参考：https://developers.facebook.com/docs/threads/reference/publishing

• Meta 官方 Postman 工作区：https://www.postman.com/meta/threads/documentation/dht3nzz/threads-api