Instagram Analytics MCP

一个用自然语言回答多个账号的 Instagram Reel 表现问题的 MCP 服务器。

重点不在于它封装了 API。而在于真正能预测触达量的数字在 Instagram API 中并不存在，因此服务器自行计算它。

"How did my last 10 reels do?"
"What worked best this month?"
"Which of my accounts is working?"

它解决的问题

Instagram 的 Graph API 返回观看量、触达量、收藏、分享和平均观看时长。

它不返回完成率——人们实际观看视频的比例。在一个真实账号上对约 700 条 Reel 的测量中，完成率是区分一条 Reel 沉没还是传播的关键：

观看量是结果。完成率是原因，而且发布后几小时内就能读取，无需等待数天。

计算它需要 avg_watch_time / duration。duration 在 API 中同样不存在。 因此服务器用 ffprobe 探测每个视频的 media_url 来测量它。

这就是它存在的全部原因。API 不会替你做的两步操作，加上 API 没有任何意见的阈值判断。

工具

每条 Reel 都会返回日期、完成率、verdict 标签、时长、观看量、触达量、收藏、分享、标题第一行作为钩子，以及永久链接。

支持一个或多个账号。account 是可选的，默认为你配置的第一个账号。

要求

• 一个 Instagram 专业账号（企业号或创作者号）。个人账号完全无法使用 Instagram API

• Python 3.10+

• ffprobe（brew install ffmpeg）——没有它就没有时长，也就没有完成率

设置

git clone https://github.com/sskghub/instagram-analytics-mcp
cd instagram-analytics-mcp

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

cp .env.example .env

然后获取一个 token。SETUP.md 是完整的操作指南，第一个账号大约需要 15 分钟：创建 Meta 应用、添加 Instagram、生成 token。

一旦 .env 中有 token，以下命令会检查一切并告诉你需要粘贴回去的账号 ID，这样你就不必自己去找：

.venv/bin/python check_setup.py

[  OK  ] mcp package installed
[  OK  ] ffprobe found
[  OK  ] main: token works, account @yourhandle

然后确认它能拉取真实数据，并且 MCP 层能端到端工作：

.venv/bin/python server.py --selftest
.venv/bin/python test_server.py

注册到 Claude Code：

claude mcp add ig-analytics -- /absolute/path/.venv/bin/python /absolute/path/server.py

服务器读取自己的 .env，因此凭据不会进入 MCP 配置文件。该配置会被提交；token 不会。

添加另一个账号只需在 .env 中添加两行。无需编辑代码——账号从变量名中自动发现。

Token 过期

Instagram token 大约持续 60 天。当其中一个失效时，下游所有内容都会静默地不返回任何数据。

refresh_tokens.py 将一个仍然有效的 token 兑换为新的 60 天 token：

python refresh_tokens.py --if-older-than 7

每周运行一次。塑造设计的关键约束是：过期的 token 无法刷新。 Meta 不会续订已失效的 token，因此提前刷新是唯一有效的策略。每次刷新都会重置完整的 60 天，所以提前刷新没有任何代价。

调度注意事项，包括 macOS 的陷阱——launchd 任务会静默地无法读取你的文件——见 SETUP.md。

它在写入前备份 .env，重写重复的键，并在失败时发出警报。

刷新不会使旧 token 失效，因此多台机器可以各自独立刷新自己的 .env。token 值永远不需要在主机之间同步。

构建笔记

那些真正耗时的事情，保留在这里，因为它们是可推广的部分。

sys.exit() 在 CLI 中没问题，在服务器中则是致命的。 第一个版本复用了现有命令行脚本中的一个函数。当 token 被拒绝时，该函数会调用 sys.exit()，这会在 token 过期的那一天杀死整个服务器进程。现在工具会抛出 ValueError；SDK 将标准异常转换为模型可以据此行动的可读结果，服务器得以存活。

错误应该说明该怎么做。 失效的 token 返回重新生成它的步骤，而不是堆栈跟踪。模型可以将其转达给真正能修复它的人。

文档字符串就是接口。 它是模型决定是否调用工具的依据，因此每个工具都说明何时使用它，而不仅仅是它返回什么。

定时任务可能静默失败。 在 macOS 上，刷新脚本的 launchd 定时器以 Operation not permitted 失败，因为 TCC 阻止后台代理读取受保护的目录。它报告为已加载，并且会静默地永远不会运行。强制运行并读取日志是唯一能发现它的方法。

.env 中的重复键是一个真正的陷阱。 过期的重复键可能会遮蔽新写入的 token，具体取决于加载器如何解析它们，因此脚本会重写每一次出现，而不仅仅是第一次。

API 改名了。 它是 mcp.server.mcpserver.MCPServer；较旧的 mcp.server.fastmcp.FastMCP 路径在 mcp 2.x 中被移除，其他遗留模块也是如此。大多数在线示例仍然使用旧的导入方式，无法运行。

许可证

MIT