Facebook Insights Metrics v23 MCP Server

A comprehensive Model Context Protocol (MCP) server that exposes Facebook Graph API v23.0 Insights metrics to any LLM via MCP tools and resources. This server provides access to 120+ Facebook metrics with intelligent search capabilities and real-time data updates.

Table of Contents

• Features
• Quick Start
• Installation
• Configuration
• MCP Tools
• MCP Resources
• Metrics Categories
• API Reference
• Development
• Contributing
• License

Features

• Complete Metrics Coverage: 121+ Facebook Graph API v23.0 Insights metrics
• Fast Fuzzy Search: Powered by Fuse.js for intelligent metric discovery
• Dynamic Updates: Parse and refresh metrics from Markdown reference
• Type Safety: Full TypeScript support with Zod validation
• MCP Compatible: Works with any MCP-compatible LLM client

Quick Start

Prerequisites

• Node.js v22.0.0 or higher
• npm or yarn
• An MCP-compatible client (Claude Desktop, Cline, etc.)

Installation

Option 1: NPM (Recommended)

# Install globally
npm install -g facebook-insights-metrics-v23

# Or install locally
npm install facebook-insights-metrics-v23

Option 2: From Source

# Clone the repository
git clone https://github.com/KarimTarekDev/facebook-insights-metrics-v23.git
cd facebook-insights-metrics-v23

# Install dependencies
npm install

# Build the project
npm run build

# Generate initial metrics data
npm run refresh

Configuration

MCP Client Configuration

Add the server to your MCP client configuration:

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "facebook-insights-metrics-v23": {
      "command": "node",
      "args": ["/path/to/facebook-insights-metrics-v23/dist/server.js"]
    }
  }
}

Cline

{
  "mcpServers": {
    "facebook-insights-metrics-v23": {
      "command": "node",
      "args": ["/path/to/facebook-insights-metrics-v23/dist/server.js"]
    }
  }
}

Environment Variables

• METRICS_DATA_PATH: Custom path to metrics.json file (optional)
• DEBUG: Enable debug logging (optional)

Quick Fix for "No parameters" Error

If you're getting "No parameters" error, run this:

# Complete setup and test
npm install && npm run build && npm run refresh && npm run test

Running the Server

# Development mode (with auto-reload)
npm run dev

# Production mode
npm run build
npm start

# Force rebuild from Markdown
npm run dev -- --rebuild

MCP Tools

The server provides the following MCP tools:

metrics.list

Returns a list of all metrics with basic information.

Response:

[
  {
    "name": "page_impressions_unique",
    "level": "page",
    "periods": ["day", "week", "days_28"],
    "dataType": "Integer",
    "deprecated": false
  }
]

metrics.get

Returns full details of a specific metric by exact name.

Parameters:

• name (string): The exact name of the metric

Response:

{
  "name": "page_impressions_unique",
  "level": "page",
  "description": "Number of people who had Page content enter their screen",
  "periods": ["day", "week", "days_28"],
  "dataType": "Integer",
  "notes": "Estimated metric",
  "tags": ["impressions", "unique"],
  "deprecated": false
}

metrics.search

Performs fuzzy search over metrics by name, description, or tags.

Parameters:

• q (string): Search query
• limit (number, optional): Maximum number of results (default: 20)

Response:

[
  {
    "item": {
      "name": "page_impressions_unique",
      "level": "page",
      "description": "Number of people who had Page content enter their screen",
      "periods": ["day", "week", "days_28"],
      "dataType": "Integer",
      "notes": "Estimated metric",
      "tags": ["impressions", "unique"],
      "deprecated": false
    },
    "score": 0.1,
    "matches": [...]
  }
]

metrics.refreshNow

Re-parses the Markdown reference file and reloads the in-memory cache.

Response:

{
  "content": [
    {
      "type": "text",
      "text": "Metrics refreshed successfully"
    }
  ]
}

MCP Resources

mcp://facebook-insights-metrics-v23/metrics.json

Complete JSON data of all Facebook Graph API v23.0 Insights metrics.

Content Type: application/json

Response:

{
  "version": "v23.0.2025-09-19",
  "updatedAt": "2025-09-19T12:00:00.000Z",
  "metrics": [
    {
      "name": "page_impressions_unique",
      "level": "page",
      "description": "Number of people who had Page content enter their screen",
      "periods": ["day", "week", "days_28"],
      "dataType": "Integer",
      "notes": "Estimated metric",
      "tags": ["impressions", "unique"],
      "deprecated": false
    }
    // ... 120+ more metrics
  ]
}

Metrics Categories

Page-Level Metrics (59 metrics)

• Page Content & Tab: Tab views and content metrics
• Page CTA & Actions: Call-to-action interactions
• Page Engagement: Follows, unfollows, and engagement metrics
• Page Impressions: Reach and impression tracking
• Page Posts Impressions: Post-specific reach metrics
• Page Video Performance: Video views and completion rates
• Page Fan/Demographics: Follower demographics and growth
• Page Content & Views: Profile page visits
• Page Stories & Activity: Story creation and activity metrics

Post-Level Metrics (33 metrics)

• Post Impressions: Post reach and visibility
• Post Engagement & Activity: Post interactions and clicks
• Post Reactions: Individual reaction counts
• Post Video Performance: Post-specific video metrics

Video Metrics (26 metrics)

• Video views, completion rates, and retention
• Demographic breakdowns by age, gender, and location
• Attribution tracking (paid vs organic)

Monetization Metrics (3 metrics)

• Content monetization earnings
• Revenue tracking and estimates

Data Types

• Integer: Counts, totals, and whole numbers
• Float: Earnings, rates, and decimal values
• JSON: Complex objects with breakdowns (demographics, attribution)
• String: Text-based data

Supported Periods

• day: Daily data points
• week: Weekly aggregated data
• days_28: 28-day rolling periods
• month: Monthly data
• lifetime: All-time totals since Page creation

CLI Options

# Force rebuild from Markdown
facebook-insights-metrics-v23 --rebuild

# Override metrics.json location
facebook-insights-metrics-v23 --data /path/to/metrics.json

Development

Project Structure

facebook-insights-metrics-v23/
├── package.json              # Project configuration
├── mcp.json                  # MCP server configuration
├── tsconfig.json             # TypeScript configuration
├── src/
│   ├── server.ts             # MCP server implementation
│   ├── schema.ts             # Zod schemas and types
│   ├── loader.ts             # Metrics data loader
│   ├── search.ts             # Fuzzy search implementation
│   ├── parser.ts             # Markdown parser
│   └── data/
│       └── metrics.json      # Generated metrics data
├── scripts/
│   └── refresh.ts            # Refresh script
└── FACEBOOK_API_V23_METRICS_REFERENCE.md  # Source markdown

Available Scripts

# Development
npm run dev          # Start server in development mode
npm run build        # Build TypeScript to JavaScript
npm run refresh      # Parse Markdown and update metrics.json

# Production
npm start            # Start built server

Adding New Metrics

1. Update the FACEBOOK_API_V23_METRICS_REFERENCE.md file
2. Run npm run refresh to parse and update metrics
3. The server will automatically reload with new metrics

Customization

• Search Threshold: Modify threshold in src/search.ts (default: 0.35)
• Data Path: Set METRICS_DATA_PATH environment variable
• Tags: Customize tag extraction in src/schema.ts

API Reference

Facebook Graph API v23.0

This MCP server is based on the official Facebook Graph API v23.0 Insights documentation. All metrics are sourced from the comprehensive reference document and include:

• Complete metric definitions
• Supported time periods
• Data types and formats
• Deprecation status
• Usage notes and limitations

Rate Limits

• MCP Server: No built-in rate limiting
• Facebook API: 200 calls per hour per app (when used with actual API)
• Search: Optimized with Fuse.js for fast local searches

Troubleshooting

Common Issues

1. "No parameters" error: This is the most common issue. Follow these steps:

   # 1. Ensure proper installation
   npm install
   npm run build
   npm run refresh
   
   # 2. Test the server
   npm run test
   
   # 3. Use correct mcp.json configuration
   

   Correct mcp.json:

   {
     "mcpServers": {
       "facebook-insights-metrics-v23": {
         "command": "node",
         "args": ["/full/path/to/facebook-insights-metrics-v23/dist/server.js"]
       }
     }
   }
   

2. No metrics found: Run npm run refresh to generate metrics.json

3. Build errors: Ensure Node.js v22+ and run npm install

4. Search not working: Check that metrics.json exists and is valid

Debug Mode

# Enable debug logging
DEBUG=* npm run dev

Development

Project Structure

facebook-insights-metrics-v23/
├── src/                          # TypeScript source code
│   ├── server.ts                 # MCP server implementation
│   ├── schema.ts                 # Zod schemas and types
│   ├── loader.ts                 # Metrics data loader
│   ├── search.ts                 # Fuzzy search implementation
│   ├── parser.ts                 # Markdown parser
│   └── data/
│       └── metrics.json          # Generated metrics data
├── scripts/
│   └── refresh.ts                # Refresh script
├── .github/                      # GitHub templates
├── dist/                         # Compiled JavaScript
├── FACEBOOK_API_V23_METRICS_REFERENCE.md  # Source markdown
└── test-mcp.js                   # Test script

Available Scripts

npm run dev          # Start development server
npm run build        # Build TypeScript to JavaScript
npm run refresh      # Parse Markdown and update metrics.json
npm start            # Start production server
npm test             # Run MCP server tests
npm run test:quick   # Quick MCP test

Adding New Metrics

1. Update FACEBOOK_API_V23_METRICS_REFERENCE.md with new metrics
2. Run npm run refresh to parse and update metrics
3. Test the new metrics with npm test

Contributing

We welcome contributions! Please see our Contributing Guide for details.

Quick Start for Contributors

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions
• 📧 Contact

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Facebook Graph API team for the comprehensive metrics documentation
• Model Context Protocol team for the MCP specification
• All contributors who help improve this project

---

Version: 1.0.0
Node.js: v22.0.0+
Facebook API: v23.0
Last Updated: September 19, 2025