Instagram MCP 服务器

这是一个提供与 Instagram 图形 API 无缝集成的 Model Context Protocol (MCP) 服务器，使 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，了解五分钟设置指南！

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

步骤 1：设置 Instagram 商业账户

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

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

2. 连接到 Facebook 页面：

   • 进入 Instagram 设置 → 账户 → 关联账户 → Facebook
   • 连接到现有的 Facebook 页面或创建一个新的页面
   • 重要：Facebook 页面必须由您拥有

步骤 2：创建 Facebook 应用

1. 前往 Facebook 开发者：

   • 访问 developers.facebook.com
   • 使用您的 Facebook 账户登录

2. 创建新应用：

   • 点击“创建应用” → 选择“商业” → 点击“下一步”
   • 填写应用详情：
     • 应用名称：选择描述性名称（例如，“我的 Instagram MCP 服务器”）
     • 应用联系电子邮件：您的电子邮件地址
   • 点击“创建应用”

3. 添加 Instagram 基础显示产品：

   • 在您的应用仪表板中，点击“添加产品”
   • 查找“Instagram 基础显示” → 点击“设置”

4. 配置 Instagram 基础显示：

   • 前往 Instagram 基础显示 → 基础显示
   • 在 Instagram 应用部分点击“创建新应用”
   • 接受条款并创建应用

步骤 3：获取应用凭证

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

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

1. 添加 Instagram 图形 API 产品：

   • 在您的应用仪表板中，点击“添加产品”
   • 查找“Instagram 图形 API” → 点击“设置”

2. 配置权限：

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

步骤 5：生成访问令牌

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

1. 前往图形 API 探索器：

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

2. 配置探索器：

   • 从下拉菜单中选择您的应用
   • 点击“生成访问令牌”
   • 当提示时选择所需的权限

3. 获取页面访问令牌：

   • 在探索器中，发出 GET 请求到：/me/accounts
   • 在响应中找到您的 Facebook 页面
   • 复制页面的 access_token

4. 获取 Instagram 商业账户 ID：

   • 使用页面访问令牌发出 GET 请求到：/{page-id}?fields=instagram_business_account
   • 从响应中复制 Instagram 商业账户 ID

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

1. 设置 Facebook 登录：

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

2. 实现 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"
   

3. 交换代码以获取令牌：

   # 交换授权码以获取访问令牌
   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())

🚨 重要安全注意事项

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

🔄 令牌刷新策略

长期令牌在 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 响应中的速率限制头

安装

1. 克隆仓库：

git clone <repository-url>
cd ig-mcp

2. 安装依赖项：

pip install -r requirements.txt

3. 设置环境变量：

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

4. 配置 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 结合使用

1. 获取个人资料信息：

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

2. 分析最近的帖子：

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

3. 发布内容：

将这张图片上传到我的 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 次调用

最佳实践

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

错误处理

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

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

安全考虑

1. 令牌安全：安全存储访问令牌
2. 环境变量：永远不要将令牌提交到版本控制系统
3. 仅 HTTPS：所有 API 调用均使用 HTTPS
4. 令牌刷新：实现自动令牌刷新
5. 审计日志：记录所有 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

贡献

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

故障排除

常见问题

1. “无效访问令牌”

   • 验证令牌是否未过期
   • 检查令牌权限
   • 重新生成长期令牌

2. “超出速率限制”

   • 等待速率限制重置
   • 实现请求队列
   • 使用批处理请求

3. “权限被拒绝”

   • 验证 Instagram 商业账户设置
   • 检查 Facebook 页面连接
   • 查看 API 权限

调试模式

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

LOG_LEVEL=DEBUG

许可证

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

支持

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

致谢

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