instagram-mcp

instagram-mcp

面向 Instagram 创作者的 MCP 服务：使用 AI Agent 和 Meta 官方 Instagram API 发布内容、安排发布时间、处理评论和私信，并查看数据洞察。可自托管；每次写入操作都需要经过你的批准。

状态：1.0.0。行为规范见 docs/CONTRACT.md，并由独立的盲测代码测试套件覆盖。该项目已在测试账号上针对 Meta 完成端到端测试（Facebook Login 路径，2026-11-01）：发布、安排发布时间、评论、私信、数据洞察、webhook 和清理。Unified Login（新应用的默认方式）也于 2026-11-01 在应用处于 Live 状态且拥有 Standard Access 时完成端到端测试：设置、令牌、读取、发布（URL 和本地文件）、安排发布时间、删除、评论写入、对话、向 Instagram Tester 发送私信，以及消息资料。尚未确认：Unified 路径上的真实 webhook 事件（Meta 的 Test 事件可以收到，但实时评论和私信事件未收到；可能需要 App Review）；Instagram Login 路径；协作邀请和品牌内容；以及需要操作其他账号的评论或 @提及的操作（隐藏评论、私密回复、回复提及）。Meta 文档说明不充分的行为列于 docs/TESTING-LIVE.md，服务能够兼容两种结果。

安装

git clone https://github.com/pratikgh0se/instagram-mcp.git && cd instagram-mcp && npm ci && npm run build

然后按照快速开始操作；如果你还没有 Meta 应用，请参阅 docs/SETUP.md。

项目简介

• 可自托管。它运行在你的计算机（或你自己的服务）上，不会经由第三方转发任何内容。令牌保存在你的钥匙串或加密文件中。
• 仅使用 Meta 官方 API。不抓取数据、不使用私有 API、不通过密码登录，也不进行浏览器自动化。
• 默认安全。使用本地传输、受 bearer 令牌保护的 HTTP、已脱敏的日志、账号允许列表，并在每次写入前请求批准。请参阅安全模型。
• 专为创作者工作流打造：42 个工具，覆盖内容发布与排期、评论处理、私信、数据洞察、报告、媒体资料包和竞品基准分析。

功能

区域	工具	功能
账号、身份验证、运维	6	已配置的账号和解析后的功能、个人资料、发布配额和速率使用情况、操作账本和审计日志、instagram_approve
媒体和归档	5	列出并读取自己的帖子和快拍、下载媒体及元数据附加文件、增量备份账号
发布内容	6	预检并发布图片、Reel、快拍、轮播帖（本地文件或 URL）、安排发布时间、查看和取消排期、删除媒体、开启/关闭评论、查看发布状态
评论、提及、收件箱	7	列出评论、统一处理收件箱（未回复、已处理）、批量回复、隐藏、取消隐藏、删除、私密回复、提及和标记的媒体、回复提及
私信	4	查看带有 24 小时窗口状态的对话、读取消息、发送消息（文本、媒体、表情回应、快捷回复）、破冰问题和持久菜单
数据洞察和报告	8	账号和媒体数据洞察、受众人口统计数据、保存的每日快照和增长数据、表现报告、最佳发布时间、媒体资料包
发现和合作	6	商业账号发现查询、最多与 10 个账号进行基准比较、话题标签搜索和媒体、协作邀请（Facebook Login 路径）

完整的工具参考文档：docs/TOOLS.md（根据实时注册表生成）。

无法执行的操作（及原因）

官方 API 不提供这些功能，因此此服务也不提供。

• 关注或取消关注账户。
• 列出你的粉丝或你关注的人。
• 点赞帖子或评论，或收藏帖子。
• 在应用中归档帖子（从个人主页隐藏）。
• 置顶帖子或评论。
• 发布后编辑说明文字。
• 读取他人的私人内容，或下载你不拥有的商业账户或创作者账户中的媒体。
• 投放合作广告（这属于 Marketing API）。
• 使用 Creator Marketplace（面向品牌方，且需要 App Review）。

已知限制

• 开发模式下的私信（facebook 登录路径）：在另一位参与者获得应用角色（Instagram Tester 角色；参见 docs/SETUP.md 第 F 节）之前，instagram_list_conversations 会返回空列表。已于 2026-11-01 确认；参见 docs/CONTRACT.md U29。
• 发送私信：在开发模式下，即使处于 24 小时窗口内，向 Instagram Tester 发送消息仍会失败，返回 MESSAGING_WINDOW_CLOSED（Meta (#10)，子代码 2534022）；应用上线后（仍为 Standard Access），同一消息发送成功（于 2026-11-01 确认，facebook 路径）。根据 Meta 的要求，向没有应用角色的人发送消息需要 instagram_manage_messages 的 Advanced Access（需 App Review；尚未测试）。对评论进行私密回复可用。
• 在 facebook 路径上，只有应用上线并订阅了该主页后，才会收到真实 webhook（评论和私信）事件（webhooks subscribe-page，默认字段为 feed，需要 pages_manage_metadata；私信不需要额外权限）。应用上线需要公开的隐私政策页面和数据删除页面；模板和免费托管步骤见 docs/legal/ 和 docs/SETUP.md 第 O 节。
• Unified Login：已于 2026-11-01 进行上线测试（应用已上线，Standard Access），涵盖设置、令牌、读取、发布、定时发布、删除、评论写入、对话、向 Instagram Tester 发送私信，以及消息个人资料；隐藏他人评论、私密回复和 @提及回复已于 2026-11-02 确认。Unified 应用未收到真实 webhook 事件（仅收到测试事件；参见 Webhooks）。话题标签搜索需要 App Review（Meta 代码 10）。
• Instagram Login：Meta 不再向应用提供仪表板中的 Instagram 登录令牌（已于 2026-11-01 确认）。已拥有该令牌的应用仍可使用此路径，但维护者未进行线上测试。
• 在 facebook 和 unified 登录路径中，instagram_get_profile 会返回 account_type: null（Graph API 不会在这些路径中提供该信息）；系统会对此发出警告。
• 提及回复仅适用于说明文字或评论中的 @提及，不适用于照片标签。

选择哪种登录方式

每个账户都配置为三种登录方式之一。它们都只使用官方端点。对于没有 Facebook Page 的新应用，应使用 Unified Login；Meta 已不再向应用提供 Instagram Login。

功能	Unified Login（新应用）	Facebook Login（for Business）	Instagram Login（旧版）
需要 Facebook Page	否（需要 business portfolio）	是	否
按 URL 发布（图片、Reel、快拍、轮播）	是（已于 2026-11-01 确认）	是	是
发布本地文件	视频通过可恢复上传（无需隧道）；图片通过媒体主机上传	视频通过可恢复上传（无需隧道）；图片仍通过媒体主机上传	图片和视频通过媒体主机上传（需要隧道）
评论、提及、数据分析、定时发布	数据分析、定时发布和对自己评论的操作（评论、回复、隐藏/取消隐藏自己的评论、删除、关闭/开启评论）：已确认。隐藏他人评论或对他人评论进行私密回复，以及提及：未测试	是	是
私信	读取和发送（应用处于 Live 状态时，可在 24 小时内向 Instagram Tester 发送）：已于 2026-11-01 确认；开场白的设置/清除已确认	读取：是（Development mode 下的角色用户）。发送：需要 Advanced Access	已试用（未验证）
删除媒体	是（已于 2026-11-01 确认）	是	已试用（未验证）
商业发现（竞品查询、基准比较）	是（读取已确认）	是	否
主题标签搜索	已试用；需要 App Review（code 10）	是	否
品牌内容和付费合作标记	已试用（需要真实赞助商进行测试）	是	已试用（未验证）
协作邀请	已试用（没有可供回复的邀请）	是	已试用（未验证）
story_insights webhook	未验证（Unified 未收到实际 webhook 事件）	是	否
令牌	系统用户令牌，永不过期	长效 Page 令牌	60 天，可由服务刷新

“已试用”表示服务会尝试调用；如果 Meta 拒绝调用，服务会记住该账户的情况，并返回 CAPABILITY_UNAVAILABLE，指出另一种登录方式。建议：没有 Page 的新应用使用 Unified Login（需要 business portfolio）；需要端到端验证的场景使用 Facebook Login。docs/SETUP.md 的 B 节可帮助你选择。

快速开始

需要 Node.js 22.13 或更高版本。安装需从源代码进行（该软件包尚未发布到 npm）。

git clone https://github.com/pratikgh0se/instagram-mcp.git
cd instagram-mcp
npm ci
npm run build

# Optional: put the CLI on your PATH. Otherwise use `node dist/cli.js` wherever this README says `instagram-mcp`.
npm link

instagram-mcp accounts add --alias main --login unified        # facebook path: --login facebook --page-id <PAGE_ID> --app-id <APP_ID>
instagram-mcp auth set-token --account main                    # hidden prompt, or pipe it on stdin; ig_user_id is found automatically
# facebook path only: instagram-mcp auth set-app-secret         (hidden prompt; the token exchange needs it)
# optional on unified: instagram-mcp auth set-app-secret --account main   (per-account secret, useful with accounts from more than one Meta app)
instagram-mcp doctor

Unified 路径需要从仪表板的“API setup with Unified login”获取令牌（参见 docs/SETUP.md 的 H2 节）；无需应用 ID 和 Page ID。facebook 路径需要三项信息：Page ID、应用 ID 和应用密钥。Graph API Explorer 令牌的有效期约为 1 小时，因此生成后应立即运行 auth set-token；如果没有应用密钥，长效令牌交换会失败，令牌也会在 1 小时内过期。

要使其正常运行，你需要一个 Professional Instagram 账户、一个 Meta 应用和一个令牌。docs/SETUP.md 会从“没有 Meta 开发者账户”开始，逐步讲解整个流程。doctor 会为每项检查打印 PASS、WARN 或 FAIL，并提供相应的修复方法。如果某项功能错误地报告 CAPABILITY_UNAVAILABLE（缓存的“否”），请使用 instagram-mcp capabilities reset --account <alias> 清除缓存。

连接 MCP 客户端

请使用绝对路径。将 /ABSOLUTE/PATH/TO/instagram-mcp 替换为你的克隆目录。对于 Claude Desktop，还要使用 command -v node 返回的绝对 node 路径（Desktop 不会读取 shell 的 PATH，因此无法通过裸 node 找到 nvm 安装的 node）。

Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "instagram": {
      "command": "/ABSOLUTE/PATH/TO/node",
      "args": ["/ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js", "serve"]
    }
  }
}

Claude Code（stdio）：

claude mcp add instagram -- node /ABSOLUTE/PATH/TO/instagram-mcp/dist/cli.js serve

HTTP 模式（在 /mcp 上使用 Streamable HTTP，必须提供 bearer token，默认仅绑定回环地址）：

instagram-mcp http-token rotate        # prints a new bearer once; stores it in your secrets backend
instagram-mcp serve --http --port 8765

claude mcp add --transport http instagram http://127.0.0.1:8765/mcp --header "Authorization: Bearer <TOKEN>"

在 HTTP 模式下，如果没有已存储的 bearer token，服务将拒绝启动；如果绑定的不是回环地址，且 http.allow_remote 不为 true，服务也将拒绝启动。INSTAGRAM_MCP_HTTP_HOST 会覆盖 http.host（--host 标志的优先级高于两者）；allow_remote 规则适用于最终生效的主机。

提示：将客户端设置为运行 instagram_approve 前先询问，其余操作则允许直接运行。这个工具是唯一会更改 Instagram 的工具。

耗时较长的审批：发布大型轮播内容（最多 20 项）可能需要几分钟，因为 Instagram 需要逐一处理每个容器。如果客户端提供进度 token，instagram_approve 会发送 MCP 进度通知；如果客户端设有请求超时（很多客户端默认是 60 秒），请启用进度时重置超时（MCP SDK 中的 resetTimeoutOnProgress），或为该工具延长超时时间。如果客户端在审批过程中终止服务，下次服务启动或查询任何操作时，该操作会被标记为 unknown；请使用 instagram_get_operation 对其进行核对。服务关闭时（stdin 关闭、收到 SIGTERM 或 SIGINT），会为正在进行的审批等待最多 INSTAGRAM_MCP_DRAIN_MS（默认 5 分钟）；收到第二个信号则立即退出。

写入操作的工作方式

所有 Instagram 端的写入操作都分为两个步骤。

1. instagram_preflight_<action> 为只读操作。它会验证输入、策略、能力、配额和媒体规格，读取当前目标状态，并返回预览、警告以及一个会过期的 approval_id（默认 10 分钟）。
2. 使用 confirm: true 调用 instagram_approve，即可严格按预览执行操作。该操作只能使用一次，会重新检查目标是否仍然存在，并记录一条审计记录。重复调用会返回已存储的结果，而不会重新执行。

config.json 中 policy 下的控制项：

• read_only: true 会使所有 preflight 和 approve 操作失败，并返回 POLICY_DENIED。
• dry_run: true 会让 instagram_approve 执行验证，并返回计划中的 Graph 调用，但不会发送任何内容。适合首次试用。
• disabled_actions: ["delete_media", "send_message"] 会禁止指定的操作。
• approval_ttl_seconds 用于设置审批有效期。
• verify_remote_media（默认 false）：设为 true 时，preflight 会解析远程媒体主机（固定 DNS），并分别发送一次 HEAD 请求；设为 false 时不会发送任何非 Meta 请求，并会返回 MEDIA_UNVERIFIED 警告。
• confirm_via_elicitation（默认 true）：当客户端支持 MCP elicitation 时，instagram_approve 会通过该机制请求你确认；拒绝确认会返回 POLICY_DENIED。

其他键：local_media_dirs（数组，默认 ["<home>/media"]）列出本地发布媒体允许使用的唯一目录；media_host.bind（默认 127.0.0.1）和 media_host.allow_remote（默认 false；绑定非回环地址时必须设为 true，例如在 Docker 中）。

发布操作绝不会重复发布：如果 media_publish 失败且结果不明确，会将结果记录为 unknown 并保存创建 ID；instagram_get_operation 会对其进行核对，而不是重试。

调度与守护进程

为 instagram_preflight_publish 提供 publish_at，会在审批通过后创建一个计划任务。该任务由守护进程执行（或通过 cron 执行 instagram-mcp scheduler run-once）：容器会在预定时间前不久创建，并在预定时间发布。超过 missed_grace_minutes（默认值为 60）所设宽限时间仍未执行的任务会标记为 missed，不会延迟发布。

instagram-mcp daemon            # scheduler, webhooks (if enabled), daily snapshots, token refresh
instagram-mcp daemon --http     # also serves the MCP endpoint over HTTP

每个状态目录运行一个守护进程。项目附带现成的 launchd 和 systemd 文件，以及一个 Dockerfile。请参阅 docs/SETUP.md 的 N 节。

Webhook

守护进程可以在 POST /webhooks/instagram 接收 Instagram Webhook（评论、提及、消息等），并使用你的应用密钥验证 X-Hub-Signature-256。它需要一个稳定的公共 HTTPS URL（可使用命名 Cloudflare Tunnel；请参阅 examples/cloudflared-config.yml）。如果未配置 Webhook，收件箱会改为轮询 API。在 Unified Login 流程中，请使用控制面板中的“3. Configure webhooks”和各账户的 Webhook Subscription 开关（无需订阅 Page）。观察结果（2026-11-01）：控制面板的 Test event 会带签名到达守护进程，并归属到 Unified 账户；但真实评论和 DM 并未发送到 Unified 应用（可能需要 App Review / Advanced Access，尚未确认），因此该流程下的收件箱依赖轮询。在 Facebook Login 流程中，运行一次 instagram-mcp webhooks subscribe-page --account <alias>，让 Meta 发送真实事件（webhooks page-subscription 可查看状态）。设置说明：docs/SETUP.md 的 O 和 P 节。

安全模型

• 密钥保存在 macOS 钥匙串、AES-256-GCM 加密文件或只读环境变量中。它们不会出现在工具输出、错误、日志、审计记录或 SQLite 数据库中。
• 状态目录权限为 0700，文件权限为 0600；如果配置文件可被组或其他用户写入、归属其他用户或是符号链接，系统会拒绝使用。在测试模式之外，系统会拒绝明文（http）API URL 覆盖值和媒体主机 URL。
• 任何以你的用户身份运行的进程都可以读取钥匙串条目；如需避免这种情况，请使用带密码短语的加密文件后端（请参阅 docs/SECURITY-MODEL.md）。
• HTTP 传输：默认仅限环回地址、必须提供 bearer 令牌（恒定时间比较）、检查 Host 和 Origin、请求体限制为 1 MB、失败请求限速、会话空闲超时以及服务器超时。
• 仅接受带有效 HMAC 签名的 Webhook。媒体主机仅为暂存文件提供无法猜测且会过期的令牌。
• 用户提供的 URL 仅通过 HTTPS 获取，并受到 SSRF 防护；下载内容仅来自 Meta CDN 主机。
• 任何工具都只能访问已配置的账户。

详情和威胁模型：docs/SECURITY-MODEL.md。安全问题报告：SECURITY.md。

文档

文档	内容
docs/SETUP.md	从新的 Meta 开发者账户开始的分步指南：应用、令牌、安装、隧道、守护进程、上线和 Webhook
docs/legal/	上线所需的隐私政策和数据删除模板
docs/TOOLS.md	生成的工具参考
docs/CONTRACT.md	行为约定
docs/TESTING-LIVE.md	端到端实测清单和未经验证的上游事实
docs/SECURITY-MODEL.md	威胁模型
AGENTS.md	供 AI Agent 安装和运行此服务的操作手册
CHANGELOG.md	发行说明
docs/superpowers/specs/2026-10-29-instagram-mcp-v1-design.md	v1 设计规范

许可证

MIT。版权所有 (c) 2026 Pratik Ghose。请参阅 LICENSE。