Provides access to Facebook Graph API v23.0 Insights metrics with 120+ metrics for analyzing page performance, post engagement, video analytics, and monetization data through comprehensive search and data retrieval tools.
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
- 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)
Option 2: From Source
Configuration
MCP Client Configuration
Add the server to your MCP client configuration:
Claude Desktop (claude_desktop_config.json)
Cline
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:
Running the Server
MCP Tools
The server provides the following MCP tools:
metrics.list
Returns a list of all metrics with basic information.
Response:
metrics.get
Returns full details of a specific metric by exact name.
Parameters:
- name(string): The exact name of the metric
Response:
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:
metrics.refreshNow
Re-parses the Markdown reference file and reloads the in-memory cache.
Response:
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:
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
Development
Project Structure
Available Scripts
Adding New Metrics
- Update the - FACEBOOK_API_V23_METRICS_REFERENCE.mdfile
- Run - npm run refreshto parse and update metrics
- The server will automatically reload with new metrics 
Customization
- Search Threshold: Modify - thresholdin- src/search.ts(default: 0.35)
- Data Path: Set - METRICS_DATA_PATHenvironment 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
- "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"] } } }
- No metrics found: Run - npm run refreshto generate metrics.json
- Build errors: Ensure Node.js v22+ and run - npm install
- Search not working: Check that metrics.json exists and is valid 
Debug Mode
Development
Project Structure
Available Scripts
Adding New Metrics
- Update - FACEBOOK_API_V23_METRICS_REFERENCE.mdwith new metrics
- Run - npm run refreshto parse and update metrics
- Test the new metrics with - npm test
Contributing
We welcome contributions! Please see our Contributing Guide for details.
Quick Start for Contributors
- Fork the repository 
- Create a feature branch: - git checkout -b feature/amazing-feature
- Make your changes 
- Run tests: - npm test
- Commit your changes: - git commit -m 'Add amazing feature'
- Push to the branch: - git push origin feature/amazing-feature
- Open a Pull Request 
Support
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
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Provides access to 120+ Facebook Graph API v23.0 Insights metrics through MCP tools and resources. Features intelligent fuzzy search capabilities and real-time metric discovery for comprehensive Facebook analytics data.