Instagram MCP Server

一个 Model Context Protocol (MCP) 服务器，提供与 Instagram Graph API 的无缝集成，使 AI 应用能够以编程方式与 Instagram 商业账户交互。

功能

🔧 工具（模型控制）

• Get Profile Info：检索 Instagram 商业账户的详细信息

• Get Media Posts：获取某个 Instagram 账户的近期帖子

• Get Media Insights：检索特定帖子的参与度指标

• Publish Media：上传并发布图片/视频到 Instagram

• Get Account Pages：列出与该账户关联的 Facebook 主页

• Get Conversations：列出 Instagram 私信会话（需要高级访问权限）

• Get Conversation Messages：读取特定会话中的消息（需要高级访问权限）

• Send DM：回复 Instagram 私信（需要高级访问权限）

📊 资源（应用程序控制）

• Profile Data：访问个人资料信息，包括粉丝数、简介等

• Media Feed：带有参与度指标的近期帖子

• Insights Data：针对帖子和账户表现的详细分析数据

💬 提示词（用户控制）

• Analyze Engagement：用于分析帖子表现的预置提示词

• Content Strategy：用于生成内容推荐的模板

• Hashtag Analysis：用于评估话题标签表现的提示词

Related MCP server: instagram-mcp

前提条件

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. 创建新应用：

   • 点击“创建应用” → 选择“商业” → 点击“下一步”

   • 填写应用详情：

     • 应用名称：选择一个描述性名称（例如“My Instagram MCP Server”）

     • 应用联系邮箱：你的电子邮件地址

   • 点击“创建应用”

3. 添加 Instagram Basic Display 产品：

   • 在应用仪表盘中，点击“添加产品”

   • 找到“Instagram Basic Display” → 点击“设置”

4. 配置 Instagram Basic Display：

   • 转到 Instagram Basic Display → Basic Display

   • 在 Instagram 应用部分点击“创建新应用”

   • 接受条款并创建应用

步骤 3：获取应用凭据

1. 获取应用 ID 和密钥：

   • 在 Facebook 应用仪表盘中，转到设置 → 基本

   • 复制你的 应用 ID 和 应用密钥

   • 重要：请妥善保管应用密钥，切勿公开分享

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

1. 添加 Instagram Graph API 产品：

   • 在应用仪表盘中，点击“添加产品”

   • 找到“Instagram Graph API” → 点击“设置”

2. 配置权限：

   • 转到 Instagram Graph API → 权限

   • 请求以下权限：

     • 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：

   • 从下拉列表中选择你的应用

   • 点击“生成访问令牌”

   • 在提示时选择所需权限

3. 获取主页访问令牌：

   • 在 Explorer 中，向 /me/accounts 发起 GET 请求

   • 在响应中找到你的 Facebook 主页

   • 复制你的主页的 access_token

4. 获取 Instagram 商业账户 ID：

   • 使用主页访问令牌向 /{page-id}?fields=instagram_business_account 发起 GET 请求

   • 从响应中复制 Instagram 商业账户 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')

📋 常见问题排查

错误：“无效的 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
# 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 端点

个人资料管理

• 获取商业账户资料信息

• 更新资料详情（未来功能）

媒体管理

• 获取近期帖子

• 获取特定媒体详情

• 上传并发布新内容

• 删除媒体（未来功能）

分析与洞察

• 帖子参与度指标（点赞、评论、分享）

• 账户洞察（触达人数、展示次数）

• 话题标签表现分析

账户管理

• 列出关联的 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    # 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. “无效的访问令牌”

   • 确认令牌未过期

   • 检查令牌权限

   • 重新生成长期令牌

2. “超出速率限制”

   • 等待速率限制重置

   • 实现请求排队

   • 使用批量请求

3. “权限被拒绝”

   • 确认 Instagram 商业账户设置

   • 检查 Facebook 主页连接

   • 检查 API 权限

调试模式

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

LOG_LEVEL=DEBUG

许可证

本项目采用 MIT 许可证授权 - 有关详细信息，请参阅 LICENSE 文件。

支持

• 📧 邮箱：support@example.com

• 🐛 问题：GitHub Issues

• 📖 文档：Wiki

致谢

• Model Context Protocol（Anthropic 出品）

• Instagram Graph API（Meta 出品）

• FastMCP，用于快速 MCP 开发