instagram-mcp

instagram-mcp

面向官方 Instagram Graph API 的 MCP 服务。通过 Claude（或任何 MCP 客户端）读取、发布内容、发表评论，并获取一个或多个 Instagram 商业/创作者账号的分析数据——符合服务条款，不使用私有或逆向工程的 API。

提供 29 种工具，涵盖账号、媒体、发布、洞察、评论、发现，以及（需审核通过的）私信。

npx-style stdio MCP · Python · FastMCP · MIT

为什么选择它

大多数“Instagram 自动化”工具要么（a）封装非官方私有 API（用户名 + 密码）——这违反 Instagram 的服务条款，并有被封禁的风险；要么（b）只能发布内容，无法读取洞察、评论或提及数据。此服务完全基于官方 Graph API 构建，从一开始就支持多账号，并覆盖完整的读取和写入功能。唯一需要 Meta 批准后才能使用的功能是私信（参见私信）。

要求

• 一个 Instagram 专业账号（商业或创作者）。个人账号无法使用 Graph API。转换免费且可撤销（Instagram 应用 → 设置 → 账号类型）。
• Instagram 账号已关联 Facebook 专页。
• 一个具有 instagram_basic + instagram_content_publish + instagram_manage_comments + instagram_manage_insights 权限的长期有效访问令牌，以及该账号的数字型 Instagram Business Account ID。具体的令牌和 ID 获取步骤请参见 SETUP.md。
• Python 3.10+。

安装

从 PyPI 安装：

pip install adelaidasofia-instagram-mcp

或从源代码安装：

git clone https://github.com/adelaidasofia/instagram-mcp
cd instagram-mcp
python3 -m venv .venv && .venv/bin/pip install -e .

将其注册到 MCP 客户端（Claude Desktop / Claude Code）——单账号零配置方式：

{
  "mcpServers": {
    "instagram": {
      "command": "instagram-mcp",
      "env": {
        "INSTAGRAM_MCP_ACCESS_TOKEN": "EAA...your-long-lived-token...",
        "INSTAGRAM_MCP_IG_USER_ID": "17841400000000000"
      }
    }
  }
}

instagram-mcp 是此软件包安装的控制台脚本。从源代码检出目录运行时，其路径为 .venv/bin/instagram-mcp；也可以直接通过 python -m instagram_mcp.server 运行模块。

或者跳过环境变量，在运行时调用 add_account（令牌会存入操作系统密钥链）。请参见多个账号。

工具

账号与健康状态 — healthcheck、list_accounts、add_account、set_default_account、remove_account、account_info

个人资料与媒体 — get_profile、list_media、get_media

洞察 — get_account_insights（覆盖人数、展示次数、个人资料浏览量、粉丝数）、get_media_insights（每篇帖子的覆盖人数、保存次数、分享次数、互动次数）、get_audience_insights（粉丝人口统计信息：年龄、性别、国家、城市）

发布 — publish_image、publish_video、publish_reel、publish_carousel（2–10 张图片）、publish_story、publishing_limit（剩余 24 小时配额）。视频/Reel 容器会异步处理；服务会轮询直到处理完成后再发布。

评论 — get_comments、reply_to_comment、hide_comment、delete_comment

发现 — search_hashtag、get_hashtag_media、get_mentions、business_discovery（通过用户名读取任意公开的专业账号）

私信 — list_conversations、get_messages、send_message（见下文）

发布内容需要使用公开的 HTTPS 媒体 URL——Instagram 会自行获取文件，因此图片/视频必须可通过开放网络访问（S3/Cloudflare/任意 CDN URL 均可）。

多个账号

运行一个服务即可管理所有账号（自己的、品牌的、客户的）。每个账号分别授权自己的令牌：

add_account(label="brand-a", access_token="EAA...", ig_user_id="178414...", make_default=True)
add_account(label="brand-b", access_token="EAA...", ig_user_id="178414...")
list_media(account="brand-b")
get_account_insights(account="brand-a")

令牌存储在 macOS 密钥链中（其他平台则存储在权限为 chmod 600 的文件中），绝不会保存在元数据文件中，也不会通过任何工具返回。任何工具都可以省略 account，以使用默认账号。

私信

DM 工具需要 instagram_manage_messages 权限，Meta 仅通过应用审核授予此权限（通常需要数周，且 2025–2026 年的审核更加严格）。在获批之前，DM 工具会明确报错并提示这一点，而不会静默地不执行任何操作。应用获批且令牌包含此权限范围后，请设置 INSTAGRAM_MCP_DM_ENABLED=1。请注意，Instagram 的标准消息时限为 24 小时。

完整的应用审核指南（录屏镜头清单、审核人员测试说明模板、隐私政策与企业验证要求、获批后启用步骤、消息标签注意事项）：docs/APP_REVIEW.md。

安全

• 出站流量受限于 Meta 主机允许列表（graph.facebook.com / graph.instagram.com）。通用 SSRF 防护（RFC1918 / 环回地址 / 链路本地地址 / CGNAT / 云元数据，DNS 解析失败时默认拒绝）会保护所有 URL 处理操作。
• 凭据绝不泄露：每个结果和错误都会经过清理器处理，在传递给模型之前移除访问令牌（包括 Meta EAA… / IGQV…）、Bearer 标头、应用密钥和 API 密钥。
• 可观测性：每次调用都会在 ~/.claude/instagram-mcp/audit.log.jsonl 中追加一条包含 4 个字段的 JSONL 审计记录（execution_time_ms、io、token_usage、error_class）。
• 每次调用 Graph 前都会进行输入验证（ID、说明文字长度、主题标签/用户名字符集、https 媒体 URL）。

许可证

MIT — 详见 LICENSE。

由 Adelaida Diaz-Roa 构建。完整安装版或团队版请访问 diazroa.com。