npm package: @fullqueso/mcp-fq-meta
Description: Full Queso Meta/Instagram Marketing MCP Server — 60 tools for insights, ads, content, page, reporting, comment intelligence, messaging, and event manager
Author: Full Queso
Latest version: 2.0.1

# mcp-fq-meta

Full Queso Meta/Instagram Marketing MCP Server — 26 tools for Instagram insights, ad management, content publishing, page management, cross-platform reporting, and comment intelligence.

## Overview

This MCP server provides programmatic access to Meta's Graph API v22.0 for the Full Queso restaurant franchise (8 locations, 80K Instagram followers). Built for use with Claude Desktop.

### Features

- **Instagram Insights** — Account metrics, media performance, top content analysis, audience demographics
- **Ad Management** — Campaign creation, ad sets, ads, performance tracking (all ads default to PAUSED for safety)
- **Content Publishing** — Post photos, carousels, and reels directly to Instagram
- **Page Management** — Facebook Page insights, post publishing, reviews
- **Cross-Platform Reporting** — Daily marketing reports, ROI calculator, content calendar analysis
- **Comment Intelligence** — Spanish comment classification for Venezuelan restaurant context

## Installation

```bash
npm install
```

## Configuration

### Environment Variables

Create a `.env` file or configure in Claude Desktop:

```env
META_APP_ID=your_app_id
META_ACCESS_TOKEN=your_system_user_token
META_BUSINESS_ID=your_business_portfolio_id
META_PAGE_ID=your_facebook_page_id
META_AD_ACCOUNT_ID=act_your_ad_account_id
META_API_VERSION=v22.0
```

### Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "fullqueso-meta": {
      "command": "/opt/homebrew/opt/node@20/bin/node",
      "args": [
        "/path/to/mcp-fq-meta/server.js"
      ],
      "env": {
        "META_APP_ID": "your_app_id",
        "META_ACCESS_TOKEN": "your_system_user_token",
        "META_BUSINESS_ID": "your_business_id",
        "META_PAGE_ID": "your_page_id",
        "META_AD_ACCOUNT_ID": "act_your_ad_account_id",
        "META_API_VERSION": "v22.0"
      }
    }
  }
}
```

## Tools Reference

### Domain 1: Instagram Insights (5 tools)

| Tool | Description |
|------|-------------|
| `get_account_insights` | Account metrics: followers, reach, impressions, profile views |
| `get_media_insights` | Performance metrics for a specific post, reel, or story |
| `get_top_content` | Rank best-performing posts by engagement, reach, or saves |
| `get_audience_demographics` | Age, gender, city, and country breakdown of followers |
| `get_stories_insights` | Metrics for recent Instagram Stories |

### Domain 2: Ad Management (7 tools)

| Tool | Description |
|------|-------------|
| `get_ad_account_overview` | Ad account summary: spend, impressions, reach, CPM, CPC, CTR |
| `get_campaign_performance` | List campaigns with performance metrics |
| `create_campaign` | Create a new ad campaign (defaults to PAUSED) |
| `create_ad_set` | Create an ad set with targeting and budget |
| `create_ad` | Create an ad from existing post or new creative |
| `pause_resume_campaign` | Pause or resume campaigns, ad sets, or ads |
| `get_ad_insights` | Detailed performance with demographic breakdowns |

### Domain 3: Content Management (6 tools)

| Tool | Description |
|------|-------------|
| `publish_photo` | Post a photo to Instagram feed |
| `publish_carousel` | Post a multi-image carousel (2-10 items) |
| `publish_reel` | Post a video reel to Instagram |
| `get_media_list` | List recent Instagram posts |
| `manage_comments` | Read, reply to, or hide comments |
| `get_hashtag_insights` | Search hashtag volume and top media |

### Domain 4: Page Management (3 tools)

| Tool | Description |
|------|-------------|
| `get_page_insights` | Facebook Page performance metrics |
| `publish_page_post` | Publish posts to Facebook Page |
| `get_page_reviews` | Get reviews and recommendations |

### Domain 5: Cross-Platform Reporting (3 tools)

| Tool | Description |
|------|-------------|
| `daily_marketing_report` | Consolidated daily report: ads + reach + engagement |
| `roi_calculator` | Compare ad spend vs organic reach for ROI analysis |
| `content_calendar_status` | Posting frequency, gaps, and consistency scoring |

### Domain 6: Comment Intelligence (2 tools)

| Tool | Description |
|------|-------------|
| `analyze_comments` | Categorize comments: praise, complaint, question, order intent, etc. |
| `get_comment_report` | Formatted intelligence report with trends and action items |

## Rate Limits

The server tracks and enforces Meta API rate limits:

- **API calls**: 200 per hour
- **Content publishing**: 25 posts per 24 hours
- **Hashtag searches**: 30 unique searches per 7 days

## Safety Features

- All ad campaigns, ad sets, and ads are created as **PAUSED** by default
- Rate limiting prevents accidental API abuse
- Token is never logged or exposed

## Architecture

```
mcp-fq-meta/
├── server.js              # MCP entry point
├── config/
│   ├── meta-config.js     # API configuration
│   └── comment-rules.js   # Spanish classification rules
├── lib/
│   ├── meta-client.js     # Graph API client
│   ├── formatter.js       # Response formatting
│   └── comment-classifier.js
├── tools/
│   ├── insights/          # Domain 1
│   ├── ads/               # Domain 2
│   ├── content/           # Domain 3
│   ├── page/              # Domain 4
│   ├── reporting/         # Domain 5
│   └── comments/          # Domain 6
└── utils/
    ├── date-helper.js
    ├── rate-limiter.js
    └── logger.js
```

## License

MIT