# meta-social-mcp

Бесплатный self-hosted MCP-коннектор для управления Facebook Page и связанным
с ней Instagram Business/Creator аккаунтом напрямую через официальный
**Meta Graph API**. Никаких платных сервисов посередине — только твой
собственный токен и этот код.

## Что умеет

**Facebook:** публиковать текстовые/фото/видео посты, планировать посты на
будущее, читать посты и комментарии, отвечать на комментарии, удалять посты,
смотреть Page Insights.

**Instagram:** публиковать фото, видео/Reels, карусели, читать медиа и
комментарии, отвечать на комментарии, смотреть инсайты по посту и по
аккаунту.

Плюс `graph_api_request` — «люк» для любого запроса к Graph API, который
пока не завёрнут в отдельный инструмент.

## Шаг 1. Создать приложение в Meta for Developers

1. Зайди на https://developers.facebook.com/apps и создай приложение
   типа **Business**.
2. В приложении добавь продукты **Facebook Login** и **Instagram Graph API**
   (Add Product → выбрать оба).
3. Пока приложение в режиме **Development** (по умолчанию), Meta **не**
   требует App Review для того, чтобы ты сам управлял своими же страницами —
   это ограничение только для чужих пользователей твоего приложения. То есть
   для личного использования полноценная модерация не нужна.

## Шаг 2. Получить токен через Graph API Explorer

1. Открой https://developers.facebook.com/tools/explorer
2. Выбери своё приложение вверху.
3. Выбери "Get User Access Token" и отметь разрешения:
   `pages_show_list`, `pages_read_engagement`, `pages_manage_posts`,
   `pages_manage_engagement`, `pages_read_user_content`,
   `instagram_basic`, `instagram_content_publish`,
   `instagram_manage_comments`, `instagram_manage_insights`,
   `read_insights`.
4. Сгенерируй User Access Token.
5. Обменяй его на **долгоживущий** токен (60 дней) через
   [Access Token Debugger](https://developers.facebook.com/tools/debug/accesstoken/)
   → кнопка "Extend Access Token", либо запросом:

   ```
   GET https://graph.facebook.com/v21.0/oauth/access_token
     ?grant_type=fb_exchange_token
     &client_id={app-id}
     &client_secret={app-secret}
     &fb_exchange_token={короткий_user_token}
   ```

6. Получив долгоживущий **User** token, забери **Page** Access Token (он не
   истекает, пока не истечёт User token):

   ```
   GET https://graph.facebook.com/v21.0/me/accounts?access_token={долгоживущий_user_token}
   ```

   В ответе для каждой твоей страницы будет `id` (это `FB_PAGE_ID`) и
   `access_token` (это `FB_PAGE_ACCESS_TOKEN`).

## Шаг 3. Найти Instagram Business Account ID

```
GET https://graph.facebook.com/v21.0/{FB_PAGE_ID}?fields=instagram_business_account&access_token={FB_PAGE_ACCESS_TOKEN}
```

Ответ вида `{"instagram_business_account": {"id": "179..."}}` — это и есть
`IG_BUSINESS_ACCOUNT_ID`. Важно: Instagram-аккаунт должен быть переведён в
Business или Creator и привязан к этой Facebook-странице (Instagram → Settings
→ Linked Accounts → Facebook).

## Шаг 4. Настроить проект

```bash
cd meta-social-mcp
npm install
cp .env.example .env
# впиши FB_PAGE_ACCESS_TOKEN, FB_PAGE_ID, IG_BUSINESS_ACCOUNT_ID в .env
```

Проверить, что сервер стартует:

```bash
node index.js
```

(Он будет молча ждать MCP-подключение по stdio — это нормально, просто
Ctrl+C для выхода.)

## Шаг 5. Подключить к Claude

### Claude Desktop / Claude Code (локально)

Добавь в `claude_desktop_config.json` (Claude Desktop → Settings → Developer
→ Edit Config) или в конфиг MCP-серверов Claude Code:

```json
{
  "mcpServers": {
    "meta-social": {
      "command": "node",
      "args": ["/полный/путь/до/meta-social-mcp/index.js"],
      "env": {
        "FB_PAGE_ACCESS_TOKEN": "...",
        "FB_PAGE_ID": "...",
        "IG_BUSINESS_ACCOUNT_ID": "..."
      }
    }
  }
}
```

Перезапусти Claude Desktop — в списке инструментов появятся `fb_*` и `ig_*`.

### Cowork / claude.ai (удалённый коннектор)

Для этого в проекте есть `http.js` — тот же коннектор, но поднятый как
веб-сервис (Streamable HTTP transport) вместо stdio. Проверено локально:
хендшейк, `tools/list` и авторизация по токену работают.

Задеплоить можно на любой хостинг, который умеет запускать Dockerfile или
Node-процесс (Render, Fly.io, Railway, свой VPS) — `Dockerfile` уже готов.
Обычно это:

1. Залить проект в свой аккаунт на выбранном хостинге (или подключить GitHub-репозиторий).
2. Задать переменные окружения: `FB_PAGE_ACCESS_TOKEN`, `FB_PAGE_ID`,
   `IG_BUSINESS_ACCOUNT_ID`, `MCP_BEARER_TOKEN` (придумай длинную случайную
   строку, например `openssl rand -hex 32` — это пароль для доступа к твоему
   коннектору).
3. Хостинг даст публичный URL вида `https://твой-сервис.onrender.com`.
4. В Cowork/claude.ai добавляешь Custom Connector с этим URL + `/mcp` на конце
   и заголовком `Authorization: Bearer <твой MCP_BEARER_TOKEN>`.

**Почему это не сделано полностью автоматически:** у меня нет и не может
быть своего аккаунта на Render/Fly.io/Railway — регистрация нового аккаунта
где-либо для тебя мне прямо запрещена политикой безопасности (это защищает
тебя от того, чтобы я создавал сервисы, привязанные не пойми к чьей личности
и почте). Плюс сам хостинг всё равно попросит подтвердить e-mail на регистрации
— это шаг, который может сделать только человек. Если скажешь, каким хостингом
пользуешься (или что готов завести новый — это 2 минуты и бесплатно), я
пройду с тобой весь процесс за штурвалом браузера и подставлю все переменные
окружения сам.

## Важно про лимиты и безопасность

- Instagram Graph API позволяет не больше **25 публикаций за 24 часа** на
  один business-аккаунт.
- `.env` с токеном никогда не должен попадать в git — `.gitignore` уже
  это учитывает.
- `fb_delete_post` необратимо удаляет пост — используй аккуратно.
- Токен даёт полный доступ к странице/аккаунту в рамках выданных разрешений
  — храни его как пароль.
- Каждый год-два Meta выпускает новую версию Graph API и отключает старые
  — если запросы начнут падать с ошибкой о версии, обнови
  `GRAPH_API_VERSION` в `.env`.