instagram-mcp

一个远程 MCP 服务器，让每位团队成员可以直接从 Claude 对话中发布 Instagram 轮播和单张图片——发布到他们自己的 Instagram 专业账号，而非其他人的。

持有者令牌标识用户身份。每个用户对应数据库中唯一一个 Instagram 账号。没有任何工具需要传入 Instagram 账号 ID 作为参数，因此通过传递错误 ID 发布到队友账号在结构上是不可能的。

Meta 应用以开发模式运行，每位团队成员均被添加为 Instagram 测试者——无需 Meta 应用审核、无需 OAuth 登录流程、无需上线。这是有意为之的设计。

连接到 Claude（将此部分原样发送给团队成员）

你需要管理员提供两样东西：服务器地址和你的个人访问令牌（以 igmcp_ 开头）。保管好令牌就像保管密码一样——持有它的人可以发布到你的 Instagram 账号。

1. 在 Claude 中，打开 设置 → 连接器 → 添加自定义连接器。

2. 粘贴以下地址：

   https://YOUR-DEPLOYMENT.vercel.app/api/mcp

   （管理员会提供真实的主机名）

3. 在连接器要求身份验证的位置，添加以下标头——左侧为名称，右侧为值：

   Authorization: Bearer igmcp_your_token_here

   标头名称：Authorization。标头值：单词 Bearer，一个空格，然后是你的令牌。没有其他内容。

4. 保存。在任何对话中，你现在可以说类似“将这 5 张幻灯片发布为带有此标题的轮播”，Claude 将上传图片并发布到你的账号。

你可以要求 Claude 执行的操作：

• 发布轮播（2–10 张图片，整个帖子一个标题）

• 发布单张图片

• 检查你今天还剩多少帖子（Instagram 限制 API 每 24 小时发布 100 条）

• 检查你的令牌健康状态（你的 Instagram 连接会在过期前自动续期；此操作会告诉你是否有任何问题）

• 列出你最近的帖子（仅限你自己的）

如果发布中途失败，只需让 Claude 再次尝试相同的发布——服务器会从中断处继续，不会重复发布。

为新团队成员进行入职（管理员）

先决条件（每人一次）：

1. 他们的 Instagram 账号必须是专业账号（商业或创作者）。

2. 在 developers.facebook.com 上打开 Meta 应用 → Instagram → API setup with Instagram Login → 将其账号添加为 Instagram 测试者。他们必须接受邀请（Instagram 应用 → 设置 → 网站权限 → 应用和网站 → 测试者邀请）。

3. 从应用仪表板为其账号生成长期访问令牌（测试者账号旁边的“生成令牌”按钮）。复制令牌并记下账号的用户 ID。

然后通过以下方式将其加入数据库（在你的机器上，在此仓库中，并已填写 .env.local）：

npm run add-member -- --name "Ada" --ig-user-id 17840000000000000 --ig-username ada.builds
# pastes the long-lived IG token when prompted (kept out of shell history)

该脚本会实时验证令牌是否与 graph.instagram.com 通信，如果令牌属于与传递的 ID 不同的账号则拒绝加入，并一次性地打印该成员的 igmcp_ 持有者令牌。通过安全渠道将其连同上面的“连接到 Claude”部分一起发送给他们。

要撤销某人：在 team_members 表中将其行上的 revoked_at 设置为 now()。他们的令牌将立即返回 401。

架构

instagram-mcp/
├── api/
│   ├── mcp.ts                 # MCP endpoint (Streamable HTTP), bearer auth wrapper
│   └── cron/refresh-tokens.ts # Vercel Cron target (daily; refreshes tokens nearing expiry)
├── src/
│   ├── auth.ts                # bearer lookup → resolves the calling member
│   ├── crypto.ts              # AES-256-GCM for IG tokens, SHA-256 for bearer hashes
│   ├── instagram.ts           # containers, polling, publish, refresh, idempotent resume
│   ├── storage.ts             # R2 uploads (per-member key prefix)
│   ├── db.ts                  # Supabase (service role)
│   ├── refresh.ts             # refresh loop shared by cron + CLI
│   └── tools/                 # one file per tool
├── scripts/
│   ├── add-member.ts          # seeds a member, generates their bearer token
│   └── refresh-tokens.ts      # manual run of the refresh loop
├── supabase/migrations/       # schema (already applied via the Supabase connector)
├── .env.example               # every key, documented
└── README.md

关键决策：

• 传输层：mcp-handler v2（Vercel 的 MCP 适配器）配合 @modelcontextprotocol/server v2——仅支持 Streamable HTTP；上游已在 v2 中移除了已弃用的 HTTP+SSE 传输，这正是我们想要的。无需自定义传输层。

• 主机：所有通信均指向 https://graph.instagram.com（Instagram 登录路径）。graph.facebook.com 属于 Facebook 登录路径，会返回误导性的令牌解析错误——大多数教程都搞错了这一点。

• 认证：每个请求携带 Authorization: Bearer <token>。令牌经过哈希（SHA-256）处理，进行查找，并用常量时间比较重新验证；未知和被撤销的令牌在任何处理之前返回 401。Instagram 令牌在 Postgres 中以 AES-256-GCM 加密存储；持有者令牌从不以原始形式存储。

• 幂等性：在调用任何 Meta API 之前，幂等性键（成员 + 图片 URL + 标题）会被写入 posts 表。子容器 ID 在创建时持久化。重试会重用已完成的子容器，仅重新创建过期的/出错子容器，并且重新发布相同的父容器 ID 是安全的（media_publish 对每个容器是幂等的）——因此半发布的轮播永远不会重复。

• 令牌刷新：Vercel Cron 每日运行；令牌有效期 60 天，每个令牌在进入 25 天续期窗口时刷新一次，因此失败运行每 24 小时有一次新的重试机会，而不是每月一次。某个成员失败不会中止循环；永久性失败（撤销访问、账号类型变更）会标记该行，并通过 check_token_health 显示，而不是无限重试。

部署（管理员）

npm install
npm run typecheck && npm test     # 19 unit tests, live tests skip without creds

vercel login
vercel link                        # or create the project
# Set every var from .env.example in Vercel → Project → Settings → Environment Variables
vercel --prod

然后将部署 URL 放入上面的“连接到 Claude”部分。

Supabase 必须是一个专用项目，仅托管此服务器——而不是与其他应用共享的项目。team_members 和 posts 是通用名称，并且 service-role 客户端拥有完整的表访问权限，因此与无关产品共享模式存在冲突（和爆炸半径）风险。在你自己的账户下创建项目，然后通过 SQL 编辑器或 Supabase MCP 连接器应用 supabase/migrations/ 中的迁移。

R2 存储桶需要启用公共访问（自定义域名或 r2.dev），匹配 R2_PUBLIC_BASE_URL。

实时验收测试

在已填写 .env.local 且至少有一个已加入的成员的情况下：

LIVE_MEMBER_BEARER_TOKEN=igmcp_...            npm test   # upload + token health, no posting
LIVE_MEMBER_BEARER_TOKEN=igmcp_... LIVE_PUBLISH=1 npm test   # ⚠ creates REAL posts
# add LIVE_MEMBER_BEARER_TOKEN_2=igmcp_... for the two-members-two-accounts test

运维说明

• 静默失败模式 #1 是令牌过期——发布停止且无人注意。Cron 会明显标记失败（非 200 状态码 → Vercel 仪表板中显示红色运行），并且 check_token_health 会报告每位成员的到期天数和刷新失败情况。

• Instagram 限制每个账号每 24 小时发布100 条帖子；get_publishing_limit 读取实时计数器。

• 容器约 24 小时后过期，每个账号最多约 50 个待处理容器——这是重试路径重用容器而非创建新容器的另一个原因。

• 保持轮播幻灯片相同的宽高比；Instagram 会将所有幻灯片裁剪为与第一张幻灯片匹配。仅支持 JPEG/PNG，≤ 8 MB。