使用说明

Instagram MCP服务器

模型上下文协议（MCP）服务器，提供与Instagram的Graph API的无缝集成，使人工智能应用程序能够以编程方式与Instagram Business帐户交互。

特性

🔧 工具（模型控制）

获取个人资料信息：检索Instagram商业资料详细信息
获取媒体帖子：从Instagram帐户获取最近的帖子
获取媒体洞察：检索特定职位的参与度指标
发布媒体：将图片/视频上传并发布到Instagram
获取帐户页面：列出连接到该帐户的Facebook页面
获取对话：列出Instagram DM对话（需要高级访问）
获取对话消息：读取特定对话中的消息（需要高级访问权限）
发私信：回复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 App Review）：

instagram_manage_messages -直接消息功能需要

⚠️ Instagram DM功能：阅读和发送Instagram私信需要Meta的高级访问批准。看 INSTAGRAM_DM_SETUP.md 应用程序审查流程。

🔑 如何获取Instagram API证书

📖 快速开始：参见身份验证_GUIDE.md 获取5分钟的设置指南！

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

步骤1：设置Instagram商业帐户

转换为商业账户 （如果还没有）：
- 打开Instagram应用程序→ 设置→ 账户→ 切换到专业帐户
- 选择“业务”→ 选择一个类别→ 完整设置
连接到Facebook页面:
- 转到Instagram设置→ 账户→ 关联账户→ 脸书
- 连接到现有的Facebook页面或创建新页面
- 重要：Facebook页面必须归您所有

第二步：创建Facebook应用

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

步骤3：获取应用凭据

获取应用ID和密码:
- 在您的Facebook应用仪表板中，转到“设置”→ Basic
- 复制您的 应用程序ID 和 应用程序密钥
- 重要：确保应用程序机密的安全，切勿公开分享

步骤4：设置Instagram Business API访问

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

步骤5：生成访问令牌

选项A：使用Facebook Graph 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流:

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

令牌交换代码:

# 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())

🚨 重要安全注意事项

从不将凭据提交到版本控制
使用环境变量或安全密钥管理
定期轮换访问令牌
监控令牌到期日期
仅在生产环境中使用HTTPS
对过期令牌实施适当的错误处理

🔄 令牌刷新策略

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

安装

克隆存储库:

git clone <repository-url>
cd ig-mcp

安装依赖项:

pip install -r requirements.txt

设置环境变量:

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

配置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一起使用

获取个人资料信息:

Can you get my Instagram profile information?

分析最近的帖子:

Show me my last 5 Instagram posts and their engagement metrics

发布内容:

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个电话

最佳实践

缓存频繁访问的数据
尽可能使用批处理请求
实现重试的指数回退
监控速率限制标头

错误处理

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

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

安全考虑

令牌安全：安全地存储访问令牌
环境变量：从不将令牌提交到版本控制
仅限HTTPS：所有API调用都使用HTTPS
令牌刷新：实现自动令牌刷新
审计日志：记录所有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

贡献

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

故障排除

常见问题

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

调试模式

通过设置启用调试日志记录：

LOG_LEVEL=DEBUG

许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

支持

📧 电子邮件：support@example.com
🐛 问题： GitHub问题
📖 文档：维基

致谢

模型上下文协议通过Anthropic
Instagram图形API 通过Meta
FastMCP 用于快速MCP开发