Instagram Mcp

@mcpware/instagram-mcp

一个模型上下文协议（MCP）服务，可与 Instagram Graph API 无缝集成，让 AI 应用能够以编程方式与 Instagram 商业账户交互。

功能

🔧 工具（由模型控制）

• 获取个人资料信息：获取 Instagram 商业资料详情
• 获取媒体帖子：获取 Instagram 账户的近期帖子
• 获取媒体洞察数据：获取特定帖子的互动指标
• 发布媒体内容：将图片/视频上传并发布到 Instagram
• 获取账户主页：列出与该账户关联的 Facebook 主页
• 获取对话：列出 Instagram 私信对话（需要高级访问权限）
• 获取对话消息：读取特定对话中的消息（需要高级访问权限）
• 发送私信：回复 Instagram 私信（需要高级访问权限）

📊 资源（由应用程序控制）

• 个人资料数据：访问个人资料信息，包括粉丝数、简介等
• 媒体动态：近期帖子及其互动指标
• 洞察数据：帖子和账户表现的详细分析数据

💬 提示词（由用户控制）

• 分析互动情况：用于分析帖子表现的预设提示词
• 内容策略：用于生成内容建议的模板
• 主题标签分析：用于评估主题标签表现的提示词

前置条件

1. Instagram 商业账户：必须关联 Facebook 主页
2. Facebook 开发者账户：API 访问所必需
3. 访问令牌：具有适当权限的长期访问令牌
4. Python 3.10+：用于运行 MCP 服务（MCP 依赖项要求）

所需的 Instagram API 权限

标准访问权限（立即可用）：

• instagram_basic
• instagram_content_publish
• instagram_manage_insights
• instagram_manage_comments
• pages_show_list
• pages_read_engagement
• pages_manage_metadata
• pages_read_user_content
• business_management

高级访问权限（需要 Meta 应用审核）：

• instagram_manage_messages - 私信功能所需

⚠️ Instagram 私信功能：读取和发送 Instagram 私信需要获得 Meta 的高级访问权限批准。有关应用审核流程，请参阅 INSTAGRAM_DM_SETUP.md。

🔑 如何获取 Instagram API 凭据

📖 快速入门：请参阅 AUTHENTICATION_GUIDE.md，查看 5 分钟设置指南！

本节将逐步介绍如何获取 Instagram MCP 服务所需的凭据。

步骤 1：设置 Instagram 商业账户

1. 切换为商业账户（如果尚未切换）：

   • 打开 Instagram 应用 → 设置 → 账户 → 切换为专业账户
   • 选择“商业” → 选择类别 → 完成设置

2. 关联 Facebook 主页：

   • 前往 Instagram 设置 → 账户 → 已关联的账户 → Facebook
   • 关联现有 Facebook 主页或创建新主页
   • 重要：你必须拥有该 Facebook 主页

第 2 步：创建 Facebook 应用

1. 前往 Facebook 开发者平台：

   • 访问 developers.facebook.com
   • 使用你的 Facebook 账号登录

2. 创建新应用：

   • 点击 "Create App" → 选择 "Business" → 点击 "Next"
   • 填写应用详情：
     • 应用名称：选择一个描述性名称（例如，"My Instagram MCP Server"）
     • 应用联系邮箱：你的电子邮箱地址
   • 点击 "Create App"

3. 添加 Instagram Basic Display 产品：

   • 在应用控制面板中，点击 "Add Product"
   • 找到 "Instagram Basic Display" → 点击 "Set Up"

4. 配置 Instagram Basic Display：

   • 前往 Instagram Basic Display → Basic Display
   • 在 Instagram App 部分，点击 "Create New App"
   • 接受条款并创建应用

第 3 步：获取应用凭据

1. 获取应用 ID 和密钥：
   • 在 Facebook 应用控制面板中，前往 Settings → Basic
   • 复制你的 App ID 和 App Secret
   • 重要：妥善保管 App Secret，切勿公开分享

第 4 步：设置 Instagram Business API 访问权限

1. 添加 Instagram Graph API 产品：

   • 在应用控制面板中，点击 "Add Product"
   • 找到 "Instagram Graph API" → 点击 "Set Up"

2. 配置权限：

   • 前往 Instagram Graph API → Permissions
   • 请求以下权限：
     • instagram_basic
     • instagram_content_publish
     • instagram_manage_insights
     • pages_show_list
     • pages_read_engagement

第 5 步：生成访问令牌

选项 A：使用 Facebook Graph API Explorer（推荐用于测试）

1. 前往 Graph API Explorer：

   • 访问 developers.facebook.com/tools/explorer

2. 配置 Explorer：

   • 从下拉菜单中选择你的应用
   • 点击 "Generate Access Token"
   • 根据提示选择所需权限

3. 获取页面访问令牌：

   • 在 Explorer 中，对 /me/accounts 发起 GET 请求
   • 在响应中找到你的 Facebook Page
   • 复制该页面的 access_token

4. 获取 Instagram Business 账号 ID：

   • 使用页面访问令牌，对 /{page-id}?fields=instagram_business_account 发起 GET 请求
   • 从响应中复制 Instagram Business 账号 ID

选项 B：使用 Facebook 登录流程（推荐用于生产环境）

1. 设置 Facebook 登录：

   • 在应用控制面板中，添加 "Facebook Login" 产品
   • 配置有效的 OAuth 重定向 URI

2. 实现 OAuth 流程：

   # Example OAuth URL
   oauth_url = f"https://www.facebook.com/v19.0/dialog/oauth?client_id={app_id}&redirect_uri={redirect_uri}&scope=pages_show_list,instagram_basic,instagram_content_publish,instagram_manage_insights"
   

3. 将代码换取令牌：

   # Exchange authorization code for access token
   token_url = f"https://graph.facebook.com/v19.0/oauth/access_token?client_id={app_id}&redirect_uri={redirect_uri}&client_secret={app_secret}&code={auth_code}"
   

第 6 步：获取长期访问令牌

短期令牌会在 1 小时后过期。将其转换为长期令牌（60 天）：

curl -X GET "https://graph.facebook.com/v19.0/oauth/access_token?grant_type=fb_exchange_token&client_id={app_id}&client_secret={app_secret}&fb_exchange_token={short_lived_token}"

第 7 步：设置环境变量

在项目根目录中创建 .env 文件：

# Facebook App Credentials
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram Access Token (long-lived)
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram Business Account ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# Optional: API Configuration
INSTAGRAM_API_VERSION=v19.0
RATE_LIMIT_REQUESTS_PER_HOUR=200
CACHE_ENABLED=true
LOG_LEVEL=INFO

第 8 步：测试设置

运行验证脚本以测试你的凭据：

python scripts/setup.py

或手动测试：

import os
import requests

# Test access token
access_token = os.getenv('INSTAGRAM_ACCESS_TOKEN')
response = requests.get(f'https://graph.facebook.com/v19.0/me?access_token={access_token}')
print(response.json())

🚨 重要安全注意事项

1. 切勿将凭据提交到版本控制系统
2. 使用环境变量或安全的密钥管理方式
3. 定期轮换访问令牌
4. 监控令牌过期日期
5. 仅在生产环境中使用 HTTPS
6. 针对过期令牌实现适当的错误处理

🔄 令牌刷新策略

长期令牌会在 60 天后过期。请实现自动刷新：

# Check token validity
def check_token_validity(access_token):
    url = f"https://graph.facebook.com/v19.0/me?access_token={access_token}"
    response = requests.get(url)
    return response.status_code == 200

# Refresh token before expiration
def refresh_long_lived_token(access_token, app_id, app_secret):
    url = f"https://graph.facebook.com/v19.0/oauth/access_token"
    params = {
        'grant_type': 'fb_exchange_token',
        'client_id': app_id,
        'client_secret': app_secret,
        'fb_exchange_token': access_token
    }
    response = requests.get(url, params=params)
    return response.json().get('access_token')

📋 常见问题排查

错误：“Invalid OAuth access token”

• 检查令牌是否已过期
• 确认令牌具有所需权限
• 确保 Instagram 账号已连接到 Facebook 公共主页

错误：“Instagram account not found”

• 确认 Instagram Business 账号 ID 正确
• 检查 Instagram 账号是否已正确关联到 Facebook 公共主页
• 确保账号类型为 Business，而非 Personal

错误：“Insufficient permissions”

• 检查 Facebook App 中所需的权限
• 使用正确的权限范围重新生成访问令牌
• 检查应用处于 Development 模式还是 Live 模式

速率限制问题

• 实现指数退避
• 尽可能缓存响应
• 监控 API 响应中的速率限制标头

安装

1. 克隆仓库：

git clone <repository-url>
cd ig-mcp

2. 安装依赖项：

pip install -r requirements.txt

3. 设置环境变量：

cp .env.example .env
# Edit .env with your Instagram API credentials

4. 配置 MCP 服务：

# Edit config.json with your specific settings

配置

环境变量（.env）

INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token
FACEBOOK_APP_ID=your_facebook_app_id
FACEBOOK_APP_SECRET=your_facebook_app_secret
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id

MCP 客户端配置

将以下内容添加到 MCP 客户端配置中（例如 Claude Desktop）：

{
  "mcpServers": {
    "instagram": {
      "command": "python",
      "args": ["/path/to/ig-mcp/src/instagram_mcp_server.py"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token"
      }
    }
  }
}

使用示例

与 Claude Desktop 搭配使用

1. 获取个人资料信息：

Can you get my Instagram profile information?

2. 分析近期帖子：

Show me my last 5 Instagram posts and their engagement metrics

3. 发布内容：

Upload this image to my Instagram account with the caption "Beautiful sunset! #photography #nature"

与 Python MCP 客户端搭配使用

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the Instagram MCP server
server_params = StdioServerParameters(
    command="python",
    args=["src/instagram_mcp_server.py"]
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        
        # Get profile information
        result = await session.call_tool("get_profile_info", {})
        print(result)

涵盖的 API 端点

个人资料管理

• 获取 Business 个人资料信息
• 更新个人资料详情（未来功能）

媒体管理

• 获取近期帖子
• 获取特定媒体详情
• 上传并发布新内容
• 删除媒体（未来功能）

分析与洞察

• 帖子互动指标（点赞、评论、分享）
• 账号洞察（覆盖人数、展示次数）
• 话题标签表现分析

账号管理

• 列出已连接的 Facebook 公共主页
• 在 Business 账号之间切换

速率限制与最佳实践

该服务会实施智能速率限制，以遵守 Instagram API 限制：

• 个人资料请求：每小时 200 次调用
• 媒体请求：每小时 200 次调用
• 发布内容：每天 25 条帖子
• 洞察：每小时 200 次调用

最佳实践

1. 缓存经常访问的数据
2. 尽可能使用批量请求
3. 对重试实施指数退避
4. 监控速率限制标头

错误处理

该服务针对常见场景提供全面的错误处理：

• 身份验证错误：令牌无效或已过期
• 权限错误：缺少所需权限
• 速率限制：自动退避重试
• 网络错误：连接超时和重试
• API 错误：Instagram 特定错误响应

安全注意事项

1. 令牌安全：安全存储访问令牌
2. 环境变量：切勿将令牌提交到版本控制系统
3. 仅使用 HTTPS：所有 API 调用均使用 HTTPS
4. 令牌刷新：实现自动令牌刷新
5. 审计日志：记录所有 API 交互

开发

项目结构

ig-mcp/
├── src/
│   ├── instagram_mcp_server.py    # Main MCP server
│   ├── instagram_client.py        # Instagram API client
│   ├── models/                    # Data models
│   ├── tools/                     # MCP tools implementation
│   ├── resources/                 # MCP resources implementation
│   └── prompts/                   # MCP prompts implementation
├── tests/                         # Unit and integration tests
├── config/                        # Configuration files
├── requirements.txt               # Python dependencies
├── .env.example                   # Environment variables template
└── README.md                      # This file

运行测试

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src/

# Run specific test file
python -m pytest tests/test_instagram_client.py

贡献

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送到分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

故障排除

常见问题

1. “Invalid Access Token”

   • 确认令牌未过期
   • 检查令牌权限
   • 重新生成长期有效令牌

2. “Rate Limit Exceeded”

   • 等待速率限制重置
   • 实现请求排队
   • 使用批量请求

3. “Permission Denied”

   • 确认 Instagram Business 账号已设置
   • 检查 Facebook 公共主页连接
   • 检查 API 权限

调试模式

通过设置以下内容启用调试日志：

LOG_LEVEL=DEBUG

故障排除

问题	原因	解决方法
me/accounts 返回空的 []	IG 未连接到 Facebook 公共主页，或者你不是主页管理员	执行步骤 1
Graph API Explorer 显示“No configuration available”	未向应用添加权限	执行步骤 3
“Generate Access Token”处于禁用状态	需要先选择“Get User Access Token”	点击“Get Token”下拉菜单
应用名称被拒绝（包含“IG”“Insta”等）	Meta 会屏蔽受商标保护的词语	使用通用名称
令牌已过期	短期令牌有效期为 1 小时	执行步骤 6，获取有效期为 60 天的令牌
(#10) To use Instagram Graph API...	IG 账号为个人账号，而非 Business 账号	在 IG 设置中切换为 Business/Creator

环境变量

变量	必需	默认值	描述
INSTAGRAM_ACCESS_TOKEN	是	—	Meta 长期访问令牌
INSTAGRAM_ACCOUNT_ID	是	—	Instagram 商业账号 ID
INSTAGRAM_API_VERSION	否	v19.0	Graph API 版本

工具（23 个）

个人资料与账号

工具	描述
get_profile_info	获取个人资料信息（简介、粉丝数、媒体数量）
get_account_pages	列出已连接的 Facebook 公共主页
get_account_insights	账号级分析数据（覆盖人数、个人资料浏览量）
validate_access_token	检查令牌是否有效

媒体与发布

工具	描述
get_media_posts	获取近期帖子及互动指标
get_media_insights	获取特定帖子的详细分析数据
publish_media	发布图片或视频
publish_carousel	发布轮播内容（2–10 张图片/视频）
publish_reel	发布 Reel
get_content_publishing_limit	检查每日发布配额

评论

工具	描述
get_comments	获取帖子的评论
post_comment	发布评论
reply_to_comment	回复评论
delete_comment	删除评论
hide_comment	隐藏/取消隐藏评论

私信

工具	描述
get_conversations	列出私信对话
get_conversation_messages	查看对话中的消息
send_dm	发送私信

发现与内容

工具	描述
search_hashtag	搜索话题标签 ID
get_hashtag_media	获取话题标签下的热门/近期媒体
get_stories	获取当前有效的限时动态
get_mentions	获取你被标记的帖子
business_discovery	查找其他商业账号

限制

以下是 Instagram Graph API 的限制，并非此工具的限制：

• 仅支持 Business/Creator 账号——不支持个人账号
• 长期令牌在 60 天后过期——请在过期前刷新
• 每小时最多 200 次 API 调用
• 每天最多发布 25 条帖子
• 私信需要 Advanced Access——需要通过 Meta 应用审核
• 话题标签搜索：每 7 天最多搜索 30 个不同的话题标签

致谢

本项目是 jlbadano/ig-mcp（Python 版）的 TypeScript 重写版本。

更多来自 @mcpware 的项目

项目	功能	安装
Claude Code Organizer	用于管理 Claude Code 记忆、技能、MCP 服务、钩子的可视化仪表板	npx @mcpware/claude-code-organizer
UI Annotator	在任意网页上悬停显示标签——AI 可按名称引用页面元素	npx @mcpware/ui-annotator
Pagecast	通过 MCP 将浏览器会话录制为 GIF 或视频	npx @mcpware/pagecast
LogoLoom	AI 徽标设计 → SVG → 导出完整品牌套件	npx @mcpware/logoloom

许可证

本项目采用 MIT 许可证授权——详情请参阅 LICENSE 文件。

支持

• 📧 邮箱：[email protected]
• 🐛 问题反馈：GitHub Issues
• 📖 文档：Wiki

致谢

• Anthropic 提供的 Model Context Protocol
• Meta 提供的 Instagram Graph API
• FastMCP，用于快速开发 MCP