STARWARCLOUD STARWAR.AI
返回市场
Instagram分析MCP

Instagram分析MCP

作者：BilalTariq012 星标更新：2025-10-12
安装使用来源：spider==github.com

项目介绍

社交分析MCP服务器

一个统一的模型上下文协议（MCP）服务器，通过Graph API提供全面的Instagram和Facebook数据分析。构建时考虑了可扩展性，以便将来轻松添加更多社交平台。

主要特性

  • 统一接口：单一MCP服务器支持多个社交平台
  • 极简配置：只需访问令牌——无需复杂设置
  • 智能发现：内置工具用于发现账户和页面
  • 丰富的提示：预建的分析提示用于常见的分析任务
  • 类型安全：完整的TypeScript实现，并具有适当的错误处理
  • 可扩展性：干净的架构，准备添加额外的平台

功能

  • Instagram账户洞察：包括印象数、覆盖人数、个人资料浏览量、粉丝数量等指标
  • Instagram媒体洞察：分析单个帖子的互动、印象、覆盖和保存情况
  • Instagram媒体管理：列出并检索有关您的Instagram帖子的详细信息
  • Instagram个人资料信息：访问账户个人资料数据，包括粉丝、简介和个人网站
  • Facebook页面洞察：提取页面级和帖子级指标，如印象数、参与用户数和页面浏览量
  • Facebook帖子列表：获取带有内联指标的帖子以进行快速分析
  • 令牌验证：检查页面访问令牌与/me端点以确认范围和有效性
  • 安全：使用环境变量进行访问令牌管理
  • 易于使用：简单的设置和与MCP兼容客户端的集成
  • 📋 Instagram媒体管理：列出并检索有关您的Instagram帖子的详细信息
  • 👤 Instagram个人资料信息：访问账户个人资料数据，包括粉丝、简介和个人网站
  • 📈 Facebook页面洞察：提取页面级和帖子级指标，如印象数、参与用户数和页面浏览量
  • 📰 Facebook帖子列表：获取带有内联指标的帖子以进行快速分析
  • ✅ 令牌验证：检查页面访问令牌与/me端点以确认范围和有效性
  • 🔒 安全：使用环境变量进行访问令牌管理
  • 🚀 易于使用：简单的设置和与MCP兼容客户端的集成

先决条件

在使用此MCP服务器之前，您需要：

Instagram需求

  1. Instagram商业账户或Instagram创作者账户
  2. Facebook页面连接到您的Instagram账户
  3. Facebook开发者账户，创建了一个应用
  4. Instagram Graph API访问令牌，具有以下权限：
    • instagram_basic
    • instagram_manage_insights
    • pages_read_engagement
    • pages_show_list

Facebook需求

  1. Facebook页面至少有30个赞（洞察需要最小受众）
  2. Facebook开发者应用，具有以下权限：
    • read_insights
    • pages_read_engagement
  3. 页面访问令牌（必须是页面令牌，而不是用户令牌）
  4. （可选）如果您计划手动运行Graph debug_token，则需要应用访问令牌

获取访问令牌

第一步：创建Facebook应用

  1. 访问Facebook开发者
  2. 点击“我的应用”→“创建应用”
  3. 选择“业务”作为应用类型
  4. 填写所需详情

第二步：添加Instagram Graph API

  1. 在您的应用仪表板中，点击“添加产品”
  2. 找到“Instagram”并点击“设置”
  3. 按照设置说明操作

第三步：生成访问令牌

  1. 转到您的应用中的Graph API Explorer
  2. 从下拉菜单中选择您的应用
  3. 点击“生成访问令牌”
  4. 选择所需的权限：
    • instagram_basic
    • instagram_manage_insights
    • pages_read_engagement
    • pages_show_list
  5. 复制生成的访问令牌

第四步：获取长期令牌（推荐）

短期令牌在一小时内过期。转换为长期令牌（有效期60天）：

curl -X GET "https://graph.facebook.com/v18.0/oauth/access_token?grant_type=fb_exchange_token&client_id=YOUR_APP_ID&client_secret=YOUR_APP_SECRET&fb_exchange_token=YOUR_SHORT_LIVED_TOKEN"

更多详情，请参阅Instagram平台文档。

安装

  1. 克隆或下载此仓库
git clone <repository-url>
cd mcp-instagram-analytics
  1. 安装依赖项
npm install
  1. 配置环境变量

在根目录创建一个.env文件：

cp .env.example .env

编辑.env并添加您的凭据：

INSTAGRAM_ACCESS_TOKEN=your_access_token_here
INSTAGRAM_ACCOUNT_ID=your_account_id_here  # 可选 - 将自动检测
  1. 构建项目
npm run build

使用方法

运行服务器

npm start

或者为了开发并自动重建：

npm run dev

配置MCP客户端

将此服务器添加到您的MCP客户端配置中。例如，在Claude Desktop的配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "instagram-analytics": {
      "command": "node",
      "args": ["/绝对路径/to/mcp-instagram-analytics/dist/index.js"],
      "env": {
        "INSTAGRAM_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

可用工具

1. list_available_accounts

列出所有连接到您的Facebook页面的Instagram商业账户。当您有多个账户时，可以使用此工具查看哪些账户可用。

参数：无

示例响应：

[
  {
    "id": "123456789",
    "username": "my_business_account",
    "name": "My Business",
    "pageId": "987654321",
    "pageName": "My Facebook Page"
  },
  {
    1. "id": "987654321",
    2. "username": "my_other_account",
    3. "name": "My Other Business",
    4. "pageId": "123456789",
    5. "pageName": "Another Page"
    6. }
]

使用场景：如果您有多个Instagram账户，首先运行此工具查看所有可用账户及其ID。然后设置INSTAGRAM_ACCOUNT_ID环境变量为您想要使用的账户ID。

2. get_user_profile

获取Instagram商业账户的个人资料信息。

参数：无

示例响应：

{
  "id": "123456789",
  "username": "your_username",
  "name": "Your Name",
  "followers_count": 1500,
  "follows_count": 300,
  "media_count": 50,
  "biography": "Your bio",
  "website": "https://yourwebsite.com"
}

3. get_account_insights

获取账户级别的洞察和分析。

参数：

  • metrics（必需）：要检索的指标数组
    • 可用：impressions、reach、profile_views、follower_count、email_contacts、phone_call_clicks、text_message_clicks、get_directions_clicks、website_clicks
  • period（必需）：时间周期（day、week、days_28）
  • since（可选）：开始日期的Unix时间戳
  • until（可选）：结束日期的Unix时间戳

示例：

{
  "metrics": ["impressions", "reach", "profile_views"],
  "period": "day"
}

4. list_media

获取最近的媒体帖子列表。

参数：

  • limit（可选）：要检索的项目数量（默认：25，最大：100）

示例响应：

[
  {
    "id": "media_id_123",
    "caption": "查看这个帖子！",
    "media_type": "IMAGE",
    "media_url": "https://...",
    "permalink": "https://instagram.com/p/...",
    "timestamp": "2024-01-15T10:30:00+0000",
    "like_count": 150,
    "comments_count": 25
  }
]

5. get_media_insights

获取特定媒体帖子的洞察。

参数：

  • media_id（必需）：媒体项目的ID
  • metrics（必需）：指标数组
    • 可用：engagement、impressions、reach、saved、video_views、likes、comments、shares

示例：

{
  "media_id": "media_id_123",
  "metrics": ["engagement", "impressions", "reach", "saved"]
}

6. get_media_details

获取特定媒体帖子的详细信息。

参数：

  • media_id（必需）：媒体项目的ID

示例使用场景

分析近期表现

  1. 使用list_media获取您的近期帖子
  2. 对每个帖子使用get_media_insights进行性能分析
  3. 比较各帖子的指标以识别哪种内容表现最佳

跟踪账户增长

  1. 使用get_account_insights与follower_count指标在days_28周期内
  2. 监控profile_views和reach以了解可见性
  3. 跟踪website_clicks以衡量流量生成

内容策略

  1. 使用get_media_insights识别顶级表现的帖子
  2. 分析engagement和saved指标
  3. 根据洞察调整内容策略

故障排除

“访问令牌无效”

  • 确保您的访问令牌具有所需的权限
  • 检查令牌是否已过期（短期令牌在一小时内过期）
  • 生成新的长期令牌

“未找到Instagram商业账户”

  • 确保您的Instagram账户是商业或创作者账户
  • 验证您的Instagram账户是否连接到Facebook页面
  • 检查当前令牌是否可以访问您的Facebook页面

“不支持的指标”

  • 某些指标仅对某些账户类型可用
  • 视频特定指标（如video_views）仅适用于视频帖子
  • 查看Instagram洞察API文档以了解指标可用性

API速率限制

Instagram Graph API有速率限制：

  • 每小时200次调用每个用户访问令牌
  • 每小时200次调用每个应用

根据需要规划使用情况并实施缓存。

开发

项目结构

mcp-instagram-analytics/
├── src/
│   ├── index.ts              # MCP服务器实现
│   ├── instagram-client.ts   # Instagram API客户端
│   └── types.ts              # TypeScript类型定义
├── dist/                     # 编译的JavaScript（生成）
├── .env                      # 环境变量（创建此文件）
├── .env.example              # 环境变量模板
├── package.json              # 依赖项和脚本
├── tsconfig.json             # TypeScript配置
└── README.md                 # 此文件

构建

npm run build

监视模式

npm run watch

贡献

欢迎贡献！请随意提交Pull Request。

许可

MIT许可 - 您可以在自己的项目中自由使用！

资源

支持

对于问题和疑问：

注意：这是一个非官方工具，与Meta、Facebook或Instagram无关。