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

npm install

Configuration

Environment Variables

Create a .env file or configure in Claude Desktop:

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:

{
  "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