Instagram MCP Server

Сервер Model Context Protocol (MCP), обеспечивающий бесшовную интеграцию с Graph API Instagram и позволяющий AI-приложениям программно взаимодействовать с бизнес-аккаунтами Instagram.

Возможности

🔧 Инструменты (управляемые моделью)

• Get Profile Info: получение деталей бизнес-профиля Instagram

• Get Media Posts: получение последних публикаций из аккаунта Instagram

• Get Media Insights: получение метрик вовлечённости для конкретных публикаций

• Publish Media: загрузка и публикация изображений/видео в Instagram

• Get Account Pages: список страниц Facebook, связанных с аккаунтом

• Get Conversations: список диалогов в личных сообщениях Instagram (требуется Advanced Access)

• Get Conversation Messages: чтение сообщений из конкретных диалогов (требуется Advanced Access)

• Send DM: ответ на личные сообщения Instagram (требуется Advanced Access)

📊 Ресурсы (управляемые приложением)

• Profile Data: доступ к информации профиля, включая количество подписчиков, био и т.д.

• Media Feed: последние публикации с метриками вовлечённости

• Insights Data: детальная аналитика по публикациям и эффективности аккаунта

💬 Промпты (управляемые пользователем)

• Analyze Engagement: готовый промпт для анализа эффективности публикаций

• Content Strategy: шаблон для генерации рекомендаций по контенту

• Hashtag Analysis: промпт для оценки эффективности хэштегов

Related MCP server: instagram-mcp

Предварительные требования

1. Instagram Business Account: должен быть связан со страницей Facebook

2. Facebook Developer Account: требуется для доступа к API

3. Access Token: долгоживущий токен доступа с соответствующими разрешениями

4. Python 3.10+: для запуска MCP-сервера (требуется зависимостями MCP)

Требуемые разрешения Instagram API

Standard Access (доступно сразу):

• 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

Advanced Access (требует Meta App Review):

• instagram_manage_messages — требуется для функций личных сообщений

⚠️ Функции Instagram DM: чтение и отправка личных сообщений Instagram требует одобрения Advanced Access от Meta. См. INSTAGRAM_DM_SETUP.md для процесса App Review.

🔑 Как получить учётные данные Instagram API

📖 Быстрый старт: см. AUTHENTICATION_GUIDE.md для руководства по настройке за 5 минут!

В этом разделе приведена пошаговая инструкция по получению необходимых учётных данных для Instagram MCP Server.

Шаг 1: Настройка бизнес-аккаунта Instagram

1. Переключитесь на бизнес-аккаунт (если ещё не сделали этого):

   • Откройте приложение Instagram → Настройки → Аккаунт → Переключиться на профессиональный аккаунт

   • Выберите «Business» → Укажите категорию → Завершите настройку

2. Подключите страницу Facebook:

   • Перейдите в Настройки Instagram → Аккаунт → Связанные аккаунты → Facebook

   • Подключите существующую страницу Facebook или создайте новую

   • Важно: страница Facebook должна принадлежать вам

Шаг 2: Создание приложения Facebook

1. Перейдите на Facebook Developers:

   • Посетите developers.facebook.com

   • Войдите с помощью своего аккаунта Facebook

2. Создайте новое приложение:

   • Нажмите «Create App» → Выберите «Business» → Нажмите «Next»

   • Заполните данные приложения:

     • App Name: выберите описательное название (например, «My Instagram MCP Server»)

     • App Contact Email: ваш адрес электронной почты

   • Нажмите «Create App»

3. Добавьте продукт Instagram Basic Display:

   • В панели управления приложением нажмите «Add Product»

   • Найдите «Instagram Basic Display» → Нажмите «Set Up»

4. Настройте Instagram Basic Display:

   • Перейдите в Instagram Basic Display → Basic Display

   • Нажмите «Create New App» в разделе Instagram App

   • Примите условия и создайте приложение

Шаг 3: Получение учётных данных приложения

1. Получите App ID и App Secret:

   • В панели управления приложением 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 выполните GET-запрос к: /me/accounts

   • Найдите свою страницу Facebook в ответе

   • Скопируйте access_token для своей страницы

4. Получите ID бизнес-аккаунта Instagram:

   • Используйте токен доступа страницы, чтобы выполнить GET-запрос к: /{page-id}?fields=instagram_business_account

   • Скопируйте ID бизнес-аккаунта Instagram из ответа

Вариант B: Использование Facebook Login Flow (рекомендуется для продакшена)

1. Настройте Facebook Login:

   • В панели управления приложением добавьте продукт «Facebook Login»

   • Настройте Valid OAuth Redirect URIs

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»

• Проверьте правильность ID бизнес-аккаунта Instagram

• Проверьте, правильно ли аккаунт Instagram связан со страницей Facebook

• Убедитесь, что аккаунт является бизнес-аккаунтом, а не личным

Ошибка: «Insufficient permissions»

• Проверьте необходимые разрешения в приложении Facebook

• Перегенерируйте токен доступа с правильными областями видимости

• Проверьте, находится ли приложение в режиме Development или Live

Проблемы с ограничением частоты запросов

• Реализуйте экспоненциальную задержку (exponential backoff)

• Кэшируйте ответы, когда это возможно

• Отслеживайте заголовки ограничения частоты в ответах 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

• Переключение между бизнес-аккаунтами

Ограничение частоты запросов и лучшие практики

Сервер реализует интеллектуальное ограничение частоты запросов для соблюдения лимитов API Instagram:

• Запросы профиля: 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. Сделайте форк репозитория

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

   • Проверьте подключение страницы Facebook

   • Проверьте разрешения API

Режим отладки

Включите журналирование отладки, установив:

LOG_LEVEL=DEBUG

Лицензия

Этот проект лицензирован в соответствии с MIT License — см. файл LICENSE.

Поддержка

• 📧 Эл. почта: support@example.com

• 🐛 Проблемы: GitHub Issues

• 📖 Документация: Wiki

Благодарности

• Model Context Protocol от Anthropic

• Instagram Graph API от Meta

• FastMCP для быстрой разработки MCP