伊格-MCP

Name: 伊格-MCP
Author: jlbadano

作者：jlbadano48 星标更新：2025-10-27

安装使用来源：spider==github.com

项目介绍

Instagram MCP 服务器

这是一个提供与 Instagram 图形 API 无缝集成的 Model Context Protocol (MCP) 服务器，使 AI 应用能够通过编程方式与 Instagram 商业账户进行交互。

功能

🔧 工具（模型控制）

获取个人资料信息：检索 Instagram 商业账户的详细资料
获取媒体帖子：从 Instagram 账户中获取最近的帖子
获取媒体洞察：检索特定帖子的互动指标
发布媒体：上传并发布图片或视频到 Instagram
获取账户页面：列出与账户关联的 Facebook 页面
获取对话：列出 Instagram 直接消息对话（需要高级访问权限）
获取对话消息：读取特定对话的消息（需要高级访问权限）
发送直发消息：回复 Instagram 直接消息（需要高级访问权限）

📊 资源（应用程序控制）

个人资料数据：访问包括关注者数量、简介等在内的个人资料信息
媒体流：带有互动指标的最近帖子
洞察数据：针对帖子和账户表现的详细分析

💬 提示（用户控制）

分析互动：用于分析帖子表现的预构建提示
内容策略：生成内容推荐的模板
标签分析：评估标签表现的提示

前提条件

Instagram 商业账户：必须连接到一个 Facebook 页面
Facebook 开发者账户：用于 API 访问
访问令牌：具有适当权限的长期访问令牌
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，了解五分钟设置指南！

本节提供了获取 Instagram MCP 服务器所需凭证的逐步指南。

步骤 1：设置 Instagram 商业账户

转换为商业账户（如果尚未转换）：
- 打开 Instagram 应用程序 → 设置 → 账户 → 切换至专业账户
- 选择“商业” → 选择一个类别 → 完成设置
连接到 Facebook 页面：
- 进入 Instagram 设置 → 账户 → 关联账户 → Facebook
- 连接到现有的 Facebook 页面或创建一个新的页面
- 重要：Facebook 页面必须由您拥有

步骤 2：创建 Facebook 应用

前往 Facebook 开发者：
- 访问 developers.facebook.com
- 使用您的 Facebook 账户登录
创建新应用：
- 点击“创建应用” → 选择“商业” → 点击“下一步”
- 填写应用详情：
  - 应用名称：选择描述性名称（例如，“我的 Instagram MCP 服务器”）
  - 应用联系电子邮件：您的电子邮件地址
- 点击“创建应用”
添加 Instagram 基础显示产品：
- 在您的应用仪表板中，点击“添加产品”
- 查找“Instagram 基础显示” → 点击“设置”
配置 Instagram 基础显示：
- 前往 Instagram 基础显示 → 基础显示
- 在 Instagram 应用部分点击“创建新应用”
- 接受条款并创建应用

步骤 3：获取应用凭证

获取应用 ID 和密钥：
- 在您的 Facebook 应用仪表板中，进入设置 → 基本
- 复制您的 应用 ID 和 应用密钥
- 重要：确保应用密钥安全且不公开分享

步骤 4：设置 Instagram 商业 API 访问

添加 Instagram 图形 API 产品：
- 在您的应用仪表板中，点击“添加产品”
- 查找“Instagram 图形 API” → 点击“设置”
配置权限：
- 前往 Instagram 图形 API → 权限
- 请求以下权限：
  - instagram_basic
  - instagram_content_publish
  - instagram_manage_insights
  - pages_show_list
  - pages_read_engagement

步骤 5：生成访问令牌

选项 A：使用 Facebook 图形 API 探索器（推荐用于测试）

前往图形 API 探索器：
- 访问 developers.facebook.com/tools/explorer
配置探索器：
- 从下拉菜单中选择您的应用
- 点击“生成访问令牌”
- 当提示时选择所需的权限
获取页面访问令牌：
- 在探索器中，发出 GET 请求到：/me/accounts
- 在响应中找到您的 Facebook 页面
- 复制页面的 access_token
获取 Instagram 商业账户 ID：
- 使用页面访问令牌发出 GET 请求到：/{page-id}?fields=instagram_business_account
- 从响应中复制 Instagram 商业账户 ID

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

设置 Facebook 登录：
- 在您的应用仪表板中，添加“Facebook 登录”产品
- 配置有效的 OAuth 重定向 URI

实现 OAuth 流程：

# 示例 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"

交换代码以获取令牌：

# 交换授权码以获取访问令牌
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 应用凭证
FACEBOOK_APP_ID=your_app_id_here
FACEBOOK_APP_SECRET=your_app_secret_here

# Instagram 访问令牌（长期）
INSTAGRAM_ACCESS_TOKEN=your_long_lived_access_token_here

# Instagram 商业账户 ID
INSTAGRAM_BUSINESS_ACCOUNT_ID=your_instagram_business_account_id_here

# 可选：API 配置
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

# 测试访问令牌
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())

🚨 重要安全注意事项

永远不要将凭证提交到版本控制系统
使用环境变量或安全的秘密管理
定期轮换访问令牌
监控令牌到期日期
仅在生产环境中使用 HTTPS
为过期令牌实现适当的错误处理

🔄 令牌刷新策略

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

# 检查令牌有效性
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

# 在过期前刷新长期令牌
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')

📋 常见问题排查

错误：“无效的 OAuth 访问令牌”

检查令牌是否已过期
验证令牌具有所需的权限
确保 Instagram 账户已连接到 Facebook 页面

错误：“未找到 Instagram 账户”

验证 Instagram 商业账户 ID 是否正确
检查 Instagram 账户是否已正确连接到 Facebook 页面
确保账户是商业账户，而不是个人账户

错误：“权限不足”

查看 Facebook 应用中的所需权限
使用正确的范围重新生成访问令牌
检查应用是在开发模式还是实时模式

速率限制问题

实现指数退避
在可能的情况下缓存响应
监控 API 响应中的速率限制头

安装

克隆仓库：

git clone <repository-url>
cd ig-mcp

安装依赖项：

pip install -r requirements.txt

设置环境变量：

cp .env.example .env
# 使用您的 Instagram API 凭证编辑 .env

配置 MCP 服务器：

# 编辑 config.json 以包含您的特定设置

配置

环境变量 (.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 结合使用

获取个人资料信息：

你能获取我的 Instagram 个人资料信息吗？

分析最近的帖子：

展示我最近 5 条 Instagram 帖子及其互动指标

发布内容：

将这张图片上传到我的 Instagram 账户，并加上标题“美丽的日落！#摄影 #自然”

与 Python MCP 客户端结合使用

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

# 连接到 Instagram MCP 服务器
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()
        
        # 获取个人资料信息
        result = await session.call_tool("get_profile_info", {})
        print(result)

API 端点覆盖

资料管理

获取商业账户资料信息
更新资料详情（未来功能）

媒体管理

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

分析与洞察

帖子互动指标（点赞、评论、分享）
账户洞察（触及、印象）
标签表现分析

账户管理

列出连接的 Facebook 页面
在商业账户之间切换

速率限制及最佳实践

服务器实现了智能速率限制以遵守 Instagram 的 API 限制：

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

最佳实践

缓存频繁访问的数据
在可能的情况下使用批处理请求
实现指数退避以重试
监控速率限制头

错误处理

服务器为常见场景提供了全面的错误处理：

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

安全考虑

令牌安全：安全存储访问令牌
环境变量：永远不要将令牌提交到版本控制系统
仅 HTTPS：所有 API 调用均使用 HTTPS
令牌刷新：实现自动令牌刷新
审计日志：记录所有 API 交互

开发

项目结构

ig-mcp/
├── src/
│   ├── instagram_mcp_server.py    # 主 MCP 服务器
│   ├── instagram_client.py        # Instagram API 客户端
│   ├── models/                    # 数据模型
│   ├── tools/                     # MCP 工具实现
│   ├── resources/                 # MCP 资源实现
│   └── prompts/                   # MCP 提示实现
├── tests/                         # 单元和集成测试
├── config/                        # 配置文件
├── requirements.txt               # Python 依赖项
├── .env.example                   # 环境变量模板
└── README.md                      # 本文档

运行测试

# 运行所有测试
python -m pytest tests/

# 运行带覆盖率的测试
python -m pytest tests/ --cov=src/

# 运行特定测试文件
python -m pytest tests/test_instagram_client.py

贡献

分叉仓库
创建功能分支 (git checkout -b feature/amazing-feature)
提交更改 (git commit -m '添加神奇功能')
推送到分支 (git push origin feature/amazing-feature)
打开 Pull Request

故障排除

常见问题

“无效访问令牌”
- 验证令牌是否未过期
- 检查令牌权限
- 重新生成长期令牌
“超出速率限制”
- 等待速率限制重置
- 实现请求队列
- 使用批处理请求
“权限被拒绝”
- 验证 Instagram 商业账户设置
- 检查 Facebook 页面连接
- 查看 API 权限

调试模式

启用调试日志记录，设置：

LOG_LEVEL=DEBUG

许可证

本项目根据 MIT 许可证发布 - 详见 LICENSE 文件。

支持

📧 邮件：support@example.com
🐛 问题：GitHub 问题
📖 文档：Wiki

致谢

Model Context Protocol 由 Anthropic 提供
Instagram 图形 API 由 Meta 提供
FastMCP 用于快速 MCP 开发