](https://mseep.ai/app/jlbadano-ig-mcp)
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_basicinstagram_content_publishinstagram_manage_insightsinstagram_manage_commentspages_show_listpages_read_engagementpages_manage_metadatapages_read_user_contentbusiness_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
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_idMCP客户端配置
将此添加到您的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
- 🐛 问题：
- 📖 文档： 维基
致谢
- 模型上下文协议 通过Anthropic
- Instagram图形API 通过Meta
- FastMCP 用于快速MCP开发