Instagram MCP Server

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 账户，而非个人账户

错误：“Insufficient permissions”

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

速率限制问题

• 实施指数退避
• 尽可能缓存响应
• 监控 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

许可证

此项目根据 MIT License 授权，详情请参阅 LICENSE 文件。

支持

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

致谢

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