mcp-instagram

Instagram 发布 MCP server —— 走官方 Graph API，同时支持 stdio 与 streamable-http 两种传输。

为飞雁（feiyan）而写，但不依赖飞雁：任何 MCP 客户端都能用。AGPL-3.0-only。

为什么自己写

Meta 没有官方 Instagram MCP（唯一的官方连接器是 Meta Ads，只管广告投放）。社区实现有几个，但全是 Graph API 的薄封装、star 个位到二十几、维护弱。既然是薄封装，与其依赖一个随时会停更的仓库，不如自己维护一份。

Related MCP server: instagram-mcp

先决条件

这三件是 Meta 的硬门槛，不是本项目能绕开的：

1. 专业账号（Business / Creator）。个人号在 API 层面被结构性排除。

2. Meta 应用 + Advanced Access：instagram_business_content_publish 权限要过 App Review 与企业验证，每次提交 2–4 周。

3. 长期访问令牌（60 天）与 IG_USER_ID。短期令牌可以用 exchangeForLongLived() 换一次；之后本服务会在剩余 7 天内自动续期。

平台硬限制（工具描述里也写了一遍）

媒体必须是 https 公网地址 —— Instagram 由服务端主动拉取，本地路径和内网地址它都取不到。把图片放到公网（对象存储 / CDN / 图床）再把 URL 交给本服务。

配置

运行

# stdio（默认）：客户端拉起本进程，一进程一账号
IG_USER_ID=... IG_ACCESS_TOKEN=... npx @feiyan/mcp-instagram

# streamable-http：常驻服务 / 容器
IG_USER_ID=... IG_ACCESS_TOKEN=... AUTH_TOKEN=$(openssl rand -hex 24) \
  npx @feiyan/mcp-instagram --http --port 18080
# 端点 http://<host>:18080/mcp，健康检查 http://<host>:18080/healthz（不鉴权）

Claude Desktop 之类的客户端配置：

{
  "mcpServers": {
    "instagram": {
      "command": "npx",
      "args": ["-y", "@feiyan/mcp-instagram"],
      "env": { "IG_USER_ID": "...", "IG_ACCESS_TOKEN": "..." }
    }
  }
}

工具

失败一律以 isError: true 返回，并把 Graph API 的错误码翻成可执行的话（例如 190 → 「重新走一次授权」，10 → 「缺 instagram_business_content_publish，去 App Review 申请 Advanced Access」）。

开发

pnpm install
pnpm build      # stdio 子进程用例测的是 dist/index.js，跑测试前先 build
pnpm test
pnpm check      # tsc --noEmit
pnpm lint

测试不打真实网络：起一个真的 node:http 假 Graph API 当夹具（mock fetch 只能证明「我以为的请求」是对的），并用真的 MCP 客户端 SDK 连 stdio 与 streamable-http 各跑一遍。